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.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.
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 |
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.
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...
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.
The maximum time selection is included in the dataset info response
as the custom x_maxTimeSelection
field.
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
).
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.
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" |