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.

---

API Description

VirES server implements the version 3.0 of the HAPI Specification.

Example HAPI Queries

• /hapi/about
• /hapi/capabilities
• /hapi/catalog
• /hapi/info?dataset=SW_OPER_MAGA_LR_1B
• /hapi/data?dataset=SW_OPER_MAGA_LR_1B&parameters=Latitude,Longitude,Radius,B_NEC,Flags_B&start=2013-11-25T11:02:52Z&stop=2013-11-25T11:03:02Z&format=json&include=header

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"