VirES for Swarm — HAPI Server

The Heliophysics Application Programming Interface (HAPI) is a community specification of a unified interface for accessing data time-series. The VirES for Swarm acts as a HAPI server and allows access to selected datasets via the HAPI interface.

For more details about see the HAPI Specification.

HAPI clients for various programming environments can be found here.

Terms and Conditions

The access and use of Swarm products are regulated by ESA's Data Policy and subject to the acceptance of the specific Terms and Conditions.

The VirES for Swarm HAPI end-point, unlike the other VirES APIs, does not require user authentication. The datasets published via the VirES for Swarm HAPI interface are accessible freely.

Available Datasets

This section list available datasets grouped by the type and their parameters (click to expand the collapsed lists). Click a dataset name to see its HAPI JSON info response.

dataset description
SW_OPER_MODA_SC_1B Swarm A S/C position from the preliminary Medium Accuracy Orbit Determination (MOD). The original SP3c records have been converted to UTC and ITRF spherical coordinates.
SW_OPER_MODB_SC_1B Swarm B S/C position from the preliminary Medium Accuracy Orbit Determination (MOD). The original SP3c records have been converted to UTC and ITRF spherical coordinates.
SW_OPER_MODC_SC_1B Swarm C S/C position from the preliminary Medium Accuracy Orbit Determination (MOD). The original SP3c records have been converted to UTC and ITRF spherical coordinates.
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF - Latitude
Longitude
double
Position in ITRF - Longitude
Radius
double
Position in ITRF - Radius
dataset description
SW_OPER_MAGA_LR_1B Swarm A vector (VFM) and scalar (ASM) magnetic field measurements interpolated at 1Hz rate.
SW_OPER_MAGB_LR_1B Swarm B vector (VFM) and scalar (ASM) magnetic field measurements interpolated at 1Hz rate.
SW_OPER_MAGC_LR_1B Swarm C vector (VFM) and scalar (ASM) magnetic field measurements interpolated at 1Hz rate.
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF - Latitude
Longitude
double
Position in ITRF - Longitude
Radius
double
Position in ITRF - Radius
F
double
Magnetic field intensity
dF_AOCS
double
Magnetic stray field correction intensity of AOCS magneto-torquer coils
dF_other
double
Magnetic stray field correction intensity of all other sources
F_error
double
Error estimate on magnetic field intensity
B_VFM[3]
double
Magnetic field vector, VFM frame
B_NEC[3]
double
Magnetic field vector, NEC frame
dB_Sun[3]
double
Magnetic stray field correction vector of Sun induced perturbation, VFM frame
dB_AOCS[3]
double
Magnetic stray field correction vector of AOCS magneto-torquer coils, VFM frame
dB_other[3]
double
Magnetic stray field correction vector of all other sources, VFM frame
B_error[3]
double
Error estimates on magnetic field, VFM frame
q_NEC_CRF[4]
double
Quaternion, transformation: NEC ← CRF
Att_error
double
Error estimates on attitude information
Flags_F
integer
Flags characterizing the magnetic field intensity measurement (F)
Flags_B
integer
Flags characterizing the magnetic field measurement
Flags_q
integer
Flags characterizing the attitude information
Flags_Platform
integer
Flags characterizing the S/C platform information
ASM_Freq_Dev
double
ASM frequency calibration data deviation
SyncStatus
integer
Synchronization status
dataset description
SW_OPER_MAGA_HR_1B Swarm A vector (VFM) magnetic field measurements at 50Hz rate.
SW_OPER_MAGB_HR_1B Swarm B vector (VFM) magnetic field measurements at 50Hz rate.
SW_OPER_MAGC_HR_1B Swarm C vector (VFM) magnetic field measurements at 50Hz rate.
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF – Latitude
Longitude
double
Position in ITRF – Longitude
Radius
double
Position in ITRF – Radius
B_VFM[3]
double
Magnetic field vector, VFM frame
B_NEC[3]
double
Magnetic field vector, NEC frame
dB_Sun[3]
double
Magnetic stray field correction vector of Sun induced perturbation, VFM frame
dB_AOCS[3]
double
Magnetic stray field correction vector of AOCS magneto-torquer coils, VFM frame
dB_other[3]
double
Magnetic stray field correction vector of all other sources, VFM frame
B_error[3]
double
Error estimates on magnetic field, VFM frame
q_NEC_CRF[4]
double
Quaternion, transformation: NEC ← CRF
Att_error
double
Error estimates on attitude information
Flags_B
integer
Flags characterizing the magnetic field measurement
Flags_q
integer
Flags characterizing the attitude information
Flags_Platform
integer
Flags characterizing the S/C platform information
SyncStatus
integer
Synchronization status
dataset description
GRACE_A_MAG GRACE 1 platform magnetometer measurements
GRACE_B_MAG GRACE 2 platform magnetometer measurements
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF - Latitude
Longitude
double
Position in ITRF - Longitude
Radius
double
Position in ITRF - Radius
B_FGM[3]
double
calibrated magnetic vector from FGM, in instrument frame
B_NEC_raw[3]
double
calibrated and aligned magnetic vector in NEC (North, East, Center) frame
B_NEC[3]
double
calibrated and aligned magnetic vector in NEC (North, East, Center) frame, 11 sample (i.e. 11 second) robust average
F
double
magnetic field intensity determined from B_NEC
q_NEC_CRF[4]
double
Quaternion, transformation: NEC <- CRF
q_error
double
experimental error indicator of attitude given in Quaternion q_NEC_CRF. Bad attitude if > approx 40
dataset description
GF1_OPER_FGM_ACAL_CORR GRACE-FO 1 platform magnetometer measurements
GF2_OPER_FGM_ACAL_CORR GRACE-FO 2 platform magnetometer measurements
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF - Latitude
Longitude
double
Position in ITRF - Longitude
Radius
double
Position in ITRF - Radius
B_FGM[3]
double
Fluxgate magnetometer, FGM, aligned, vector-vector calibrated and corrected for satellite disturbances, FGM frame
B_NEC[3]
double
Fluxgate magnetometer, FGM, aligned, vector-vector calibrated and corrected for satellite disturbances, NEC frame
q_NEC_FGM[4]
double
Quaternion, transformation: NEC ... FGM
dB_MTQ_FGM[3]
double
Disturbance field related to magnetorquer, FGM frame
dB_XI_FGM[3]
double
Disturbance field related to 2nd order non-linearities, FGM frame
dB_NY_FGM[3]
double
Disturbance field related to 3rd order non-linearities, FGM frame
dB_BT_FGM[3]
double
Disturbance field related to temperature dependency of offsets, FGM frame
dB_ST_FGM[3]
double
Disturbance field related to temperature dependency of scale factors, FGM frame
dB_SA_FGM[3]
double
Disturbance field related to solar array currents, FGM frame
dB_BAT_FGM[3]
double
Disturbance field related to battery currents, FGM frame
B_FLAG
integer
Flags
dataset description
CS_OPER_MAG Cryosat-2 Platform magnetometer measurements
parameter / type description
Timestamp
isotime
Time stamp
Latitude
double
Position in ITRF - Latitude
Longitude
double
Position in ITRF - Longitude
Radius
double
Position in ITRF - Radius
B_FGM1[3]
double
calibrated magnetic vector from FGM1, in instrument frame
B_FGM2[3]
double
calibrated magnetic vector from FGM2, in instrument frame
B_FGM3[3]
double
calibrated magnetic vector from FGM3, in instrument frame
B_NEC1[3]
double
calibrated and aligned magnetic vector from FGM1, in NEC (North, East, Center) frame
B_NEC2[3]
double
calibrated and aligned magnetic vector from FGM2, in NEC (North, East, Center) frame
B_NEC3[3]
double
calibrated and aligned magnetic vector from FGM3, in NEC (North, East, Center) frame
B_NEC[3]
double
calibrated and aligned magnetic vector in NEC (North, East, Center) frame, 5 sample (i.e. 20 second) robust average of all 3 FGM
F
double
magnetic field intensity determined from B_NEC
B_mod_NEC[3]
double
CHAOS-6 model field (core, crust + magnetosphere), in NEC (North, East, Center) frame
q_NEC_CRF[4]
double
Quaternion, transformation: NEC <- CRF
q_error
double
experimental error indicator of attitude given in Quaternion q_NEC_CRF. Bad attitude if > approx 40

API Description

VirES server implements the version 3.0 of the HAPI Specification.

Example HAPI Queries

Data Request Limits

The time selection of one HAPI data request is currently limited to a time selection of approx. 432,000 data records (equivalent of 5 days of 1Hz MAGx_LR_1B data or 2 hours and 24 minutes of 50Hz MAGx_HR_1B data), which is the same limit as the one applied to the synchronous VirES API requests.

This number of records is converted to a time period by multiplication with the nominal cadence of the dataset (see x_maxTimeSelection in the dataset info) which is then used as the actual hard limit. For irregularly sampled datasets, the number of the actual records may slightly differ from the nominal limit.

If you need to retrieve more data than this limit, please consider splitting your large requests into smaller chunks.

Custom Extensions

The HAPI Specification allows extension of the protocol as long as these do not collide with the baseline specification and can be safely ignored by client which do not recognize them. The extension attributes are labelled by the x_ prefix.

The VirES extensions are described below...

Dataset Name and Type

The info responses contain extra x_dataset and x_datasetType for the VirES product collection (equal to the HAPI dataset name) and VirES product type. Datasets of the same x_datasetType bear the identical set of parameters.

Maximum Time Selection

The maximum time selection is included in the dataset info response as the custom x_maxTimeSelection field.

Storage Data Type

The parameters description contains additional attribute x_type publishing original storage data type of the parameter and its bit-size (int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32 or float64).

In case of the time-stamps, the description defines the original time-encoding with these attributes: x_standard (UTC), x_epoch (zero-time instant, 1970-01-01T00:00:00Z), x_unit (time unit of the stored numbers, e.g. s, ms, or us) and x_type (storage data type, int64).

The string arrays contain an additional x_encoding attribute (ASCII or UTF-8).

Custom Binary Format

VirES provides an extra custom binary format x_binary. This format has the same structure and endianity as the HAPI binary format but the time, integer and floating point values are encoded in their source data type indicated by the x_type, rather than by the ISO‑8601 time string, 32‑bits signed integer and double precision float.

This binary format is a bit faster to produce, more compact than the standard binary format and it can safely represent uint32, int64, and uint64 values.

JSON Representation of Special IEEE 745 Values

The number representation in the JSON format is limited to decimal numbers (-123.456) with the optional exponential notation (-1.23456e2). JSON cannot represent the IEEE 745 special not-a-number and positive or negative infinity values which may occur in the provided time series data.

VirES for Swarm HAPI server encodes these values as strings which are parsable by the Javascript Number() and Python float() functions:

special valueJSON representation
not-a-number"NaN"
positive infinity"Infinity"
negative infinity"-Infinity"