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.

`SW_MODx_SC_1B`

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

`SW_MAGx_LR_1B`

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

`SW_MAGx_HR_1B`

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

`GRACE_x_MAG`

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

`GFx_FGM_ACAL`

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

`CS_MAG`

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 value	JSON representation
not-a-number	`"NaN"`
positive infinity	`"Infinity"`
negative infinity	`"-Infinity"`