SWE HAPI Server

This page describes the HAPI Server of ESA's Space Weather Portal. It briefly gives an overview on what the SWE HAPI Server is and describes how to use it along with some practical real-world examples. Please note that the SWE HAPI Server is only available to registered users and requires authentication prior to using it for data and information retrieval.

Table of contents

• What is the SWE HAPI Server
• How to use the SWE HAPI Server
  • Basics and first steps
    1. Registration
    2. Authentication
    3. Access HAPI
  • Helper scripts
    • Python SWE_HAPI class
  • HAPI endpoints
    • HAPI endpoint /info
    • HAPI endpoint /data
  • Limitations
• Examples
  • Get a list of available datasets
  • Get information about a dataset
  • Get data from a dataset

What is the SWE HAPI Server

HAPI stands for Heliophysics Application Programmer's Interface (HAPI). The HAPI data access specification is a RESTful API and streaming format specification for delivering digital time series data. The HAPI specification was recommended by COSPAR in 2018 as the common data access API for space science and space weather data. The SWE HAPI Server is an implementation of the HAPI specification.

HAPI provides three major functionalities to a user. Firstly, the HAPI catalog lists all available datasets. Secondly, for each available dataset, HAPI provides general information about the dataset and the data it holds. Thirdly, HAPI can be used to download data from a given dataset for a specified time range. More details about these possibilities along with some real-world examples can be found in the sections below. More information about the HAPI specification can be found on https://hapi-server.org/ and on the HAPI specification GitHub project. Furthermore, examples and client libraries can be found on the HAPI GitHub project page.

The currently implemented HAPI specification version can be found on the HAPI Server landing page as well as on the /about HAPI endpoint. The landing page further also links to the concrete specification description.

🔝 Go to top

How to use the SWE HAPI Server

To use the SWE HAPI Server, a user account with ESA's Space Weather Portal is required. To access HAPI within the browser, the user simply needs to be logged into the portal. In such a case, simple requests as outlined in the examples below can be submitted within the browser session.

For a programmatic access to HAPI, machine-to-machine (M2M) credentials must be requested first. With the obtained M2M credentials, the user (via a script, an app, or other programmatic methods) must authenticate against the SSO server to retrieve an access token for submitting requests to HAPI.

The SSO and Machine-to-Machine Interfaces (M2M) page describes in general how to use the SSO to obtain access tokens to access a variety of products within the SWE Network. The information on this page is tailored for the use with the SWE HAPI Server.

🔝 Go to top

Basics and first steps

To interact with the SWE HAPI Server, the following steps must be executed as depicted in the below figure:

1. Registration (only once)
2. Authentication (yielding a token used for every interaction with HAPI)
3. Access HAPI

These steps are described in more detail in the following sections. As HAPI is an API (Application Programmer's Interface), it is assumed that the user is capable of using the command line and that they have basic programming abilities. The below examples are carried out using the cURL command line tool which is available on all major operating systems. For convenience, Bash and Python scripts are also provided below.

🔝 Go to top

1. Registration

To register with the SWE Portal, use the registration form that can be found here.

After successful registration and login to the portal, the M2M credentials must be requested. Please select "New M2M request" on the OIDC Client Self-Enrolment app (or simply click here to open the request form directly). After submitting the request, two items will be returned (the secret will only appear after clicking "Retrieve credentials"):

• Client-ID - a string of characters similar to the below

  • fdcad2908e964bbc8ca4ed25bdf25e1b

• Client-Secret - a string of characters similar to the below

  • PRPATrPBjgo2y3akZ4f28a1cb9cDDsPRP9Bjgo2fe

The steps in this section need to be executed only once. However, it is advisable to renew the M2M credentials periodically for increased security. As with all credentials, the M2M credentials must be kept secret and shall not be passed to other parties. Please also note that the provided strings on this page are just examples and will not work on our systems.

🔝 Go to top

2. Authentication

As mentioned above, when HAPI is opened in a browser, it will rely on OIDC browser-based flow, allowing the user to use the same personal account that is used to sign-in into the SWE Portal. All HAPI endpoints are available, and data can be requested as described in the below examples.

The M2M credentials can be used to access HAPI programmatically. For this purpose, an access token must be obtained from the SSO server by providing the obtained M2M credentials scoped for the SWE HAPI server. This is done by providing the credentials as well as scope=swe_hapiserver with the request to the SSO. The below code snippet shows this request using cURL. <CLIENT-ID> and <CLIENT-SECRET> must be replaced with the M2M credentials obtained in step 1 (Registration).

curl \
-d 'client_id=<CLIENT_ID>' \
-d 'client_secret=<CLIENT_SECRET>' \
-d 'grant_type=client_credentials' \
-d 'scope=swe_hapiserver' \
'https://sso.s2p.esa.int/realms/swe/protocol/openid-connect/token'

This request will return a json structure similar to the one below containing the access token to be used for subsequent HAPI access. Please note that the below response is provided in pretty print and the actual response received may not include line breaks or spaces.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiw...",
    "expires_in": 300,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "swe_hapiserver"
}

The access token (access_token) in the above example has been shortened for improved readability (the token typically has more than 1000 characters). The response also contains further information such as the scope (the application this access token is valid for, in this case the SWE HAPI Server swe_hapiserver) and how long the token is valid for (expires_in). The token will expire within 300 seconds (5 minutes). This means that subsequent requests to HAPI with this access token must be made within 5 minutes. Afterwards, a new access token must be requested from the SSO server, as the client_credentials grant does not include refresh tokens.

🔝 Go to top

3. Access HAPI

With the access token obtained in step 2 (Authentication), any HAPI endpoint can be accessed to retrieve the respective information. The available endpoints are described in the following sections along with real-world examples. To showcase how to use the obtained access token, the HAPI /capabilities endpoint is used in the below code snippet.

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
'https://swe.ssa.esa.int/hapi/capabilities'

A successful request to the /capabilities endpoint will yield the below response from the SWE HAPI Server. Please note that as in the above example the below response is provided in pretty print and the actual response received might not include neither line breaks nor spaces.

{
    "HAPI": "3.0.0",
    "status": {
        "code": 1200,
        "message": "OK"
    },
    "outputFormats": [
        "csv",
        "json"
    ]
}

Crucial for a successful response from HAPI are the "code": 1200 and "message": "OK" fields of the JSON response along with an HTTP code 200. If the access was not successful, the most common issue will be that the authentication was not successful in which case an HTTP code 401 (Not Authenticated) will be returned from the HAPI server. Please repeat step 2 (Authentication) before trying to access the SWE HAPI Server again with a new access token.

In a similar way, any other endpoint of HAPI can be accessed for the respective purpose. More details and examples on the usage of HAPI can be found in the following sections.

🔝 Go to top

Helper scripts

For convenience two basic helper scripts can be downloaded from the SWE Portal. These scripts retrieve an access token from the SSO server for subsequent use with HAPI (or another protected application, such as the SWE Content Proxy). The scripts are provided for Bash and Python, respectively. They can be downloaded here:

• get_hapi_access_token.sh
• get_hapi_access_token.py

To get the help page for how to use the scripts, execute the scripts and provide the -h flag:

./get_hapi_access_token.sh -h

python3 get_hapi_access_token.py -h

The following example code snippet shows how to use the Bash script to retrieve the /catalog endpoint from HAPI:

ACCESS_TOKEN=$(./get_hapi_access_token.sh -s -i $CLIENT_ID -x $CLIENT_SECRET)
curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://swe.ssa.esa.int/hapi/catalog"

The below example code snippet shows how the Python script can be used to request the /catalog endpoint from HAPI:

import get_hapi_access_token

access_token, access_token_timestamp = get_oauth2_access_token(client_id, client_secret)
if access_token and is_token_valid(access_token, access_token_timestamp):
    auth_header = {"Authorization": f"Bearer {extract_access_token(access_token)}"}
    response = requests.get("https://swe.ssa.esa.int/hapi/catalog", headers=auth_header)

The other endpoints can be requested in the same way.

🔝 Go to top

Python SWE_HAPI class

For convenience and to help prototyping a Python-based application using HAPI, the SWE_HAPI class was implemented. It handles authentication and implements basic methods to retrieve data from the HAPI endpoints /catalog, /info, and /data. This class can be further tailored to fit the respective needs. The methods can be extended to, for instance, only request required parameters. The full bundle can be downloaded here:

• SWE_HAPI.zip

The below example shows how to use the SWE_HAPI class to request the three endpoints from the SWE HAPI Server. These requests are analogous to the examples given in the sections Get information about a dataset and Get data from a dataset.

import SWE_HAPI

swe_hapi = SWE_HAPI(client_id, client_secret)
catalog = s2ph.get_hapi_catalog()
info = s2ph.get_hapi_info("spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1")
data = s2ph.get_hapi_data("spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1", "2026-03-25T12:00:00Z", "2026-03-25T12:05:00Z")

🔝 Go to top

HAPI endpoints

The SWE HAPI Server exposes the following 5 REST-like endpoints that will respond to HTTP GET requests. This information can also be found on the HAPI landing page. All endpoints require authentication.

1. /capabilities describes the capabilities of the server; it lists the output formats the server can emit (typically CSV and JSON)
2. /catalog lists the datasets that are available; each dataset is associated with a unique id
3. /info to obtain the description for a dataset of a given id; the description defines the parameters in every dataset record
4. /data to stream data content for a dataset of a given id; the streaming request must have time bounds (specified by request parameters start and stop) and may indicate a subset of parameters (default is all parameters)
5. /about provides server description metadata, which contains server name, contact information or email address for server issues, identifier in the discovery system for information about the contact.

The endpoints /capabilities, /catalog, and /about don't take any additional parameters and simply respond providing the respective information.

The /info and /data endpoints as well as their required and optional parameters are described in more detail in the following sections.

🔝 Go to top

HAPI endpoint /info

This endpoint returns information about a given dataset. For this endpoint the below parameters are specified and required parameters must be passed to the endpoint.

Request:

Response:

The response is returned in JSON format and provides details about the (requested) parameters along with additional metadata information on the dataset itself. The response typically contains the following fields:

More details about the endpoint can be found by visiting the respective HAPI specification of the currently implemented HAPI version.

🔝 Go to top

HAPI endpoint /data

This endpoint returns data from a given dataset. For this endpoint the below parameters are specified and required parameters must be passed to the endpoint.

Request:

Response:

The response is returned in the requested format and contains the data for the requested parameters and the requested time range.

More details about the endpoint can be found by visiting the respective HAPI specification of the currently implemented HAPI version.

🔝 Go to top

Limitations

Currently, the access to data and metadata through the SWE HAPI Server is restricted to specific data sets. A list of accessible data sets can be obtained by requesting the /catalog endpoint. Items listed in the catalog can be retrieved in terms of both /info and /data endpoints.

Furthermore, HAPI’s responses on requests to the /data endpoint are limited to a maximum of 100,000 data elements per response and an overall response size of 12,288 kB. These limits are set on the server side and cannot be changed by the user. The user is advised to request a smaller time range if a related error message is returned by the SWE HAPI Server.

🔝 Go to top

Examples

This section provides some real-world examples on how to use the SWE HAPI Server for retrieval of dataset information and data for a given time range. Three typical scenarios are covered as shown in the below figure.

1. Get a list of available datasets
   to identify the dataset of interest from the list
2. Get information about a dataset
   to learn about the available data and metadata of the dataset
3. Get data from a dataset
   to request data from the dataset

All examples require a valid access token to be obtained as outlined in step 2 (Authentication) above. 

🔝 Go to top

Get a list of available datasets

In this example, we request the full catalog from the /catalog endpoint of the SWE HAPI Server to identify which datasets are available for the subsequent example requests.

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
'https://swe.ssa.esa.int/hapi/catalog'

Response (in pretty print and shortened to only 3 datasets):

{
  "HAPI": "3.0.0",
  "status": {
    "code": 1200,
    "message": "OK"
  },
  "catalog": [
    {
      "id": "spase://SSA/NumericalData/D3S/d3s_gk2a_sosmag_recalib",
      "title": "SOSMAG-GK2A-L2 (ESA)"
    },
    {
      "id": "spase://SSA/NumericalData/D3S/d3s_mtgi1_ngrm_science_ep_l1_gc_v1",
      "title": "MTG-I1/NGRM differential electron fluxes (ESA)"
    },
    ...
    {
      "id": "spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1",
      "title": "MTG-S1/NGRM integral electron and differential proton fluxes (ESA)"
    }
  ]
}

🔝 Go to top

Get information about a dataset

In this example, we use the /info endpoint to request the full information about the MTG-S1/NGRM integral electron and differential proton fluxes (ESA) dataset (dataset id spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1) - the last item listed in the above example response.

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
'https://swe.ssa.esa.int/hapi/info?dataset=spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1'

Response (in pretty print and shortened to list only 3 parameters):

{
  "HAPI": "3.0.0",
  "status": {
    "code": 1200,
    "message": "OK"
  },
  "format": "json",
  "parameters": [
    {
      "name": "utc",
      "type": "isotime",
      "length": 24,
      "size": [
        1
      ],
      "units": "UTC",
      "fill": null,
      "description": "Timestamp in coordinated Universal Time (UTC)",
      "label": [
        "Time"
      ]
    },
    {
      "name": "feio_1",
      "type": "double",
      "size": [
        1
      ],
      "units": "cm^-2 s^-1 sr^-1",
      "fill": "-1.0e+31",
      "description": "Omnidirectional integral electron flux.\nFluxes were obtained from L0 counts using geometric factors derived with the Bow-Tie method.",
      "label": [
        "Integral electron flux (>0.15 MeV)"
      ]
    },
    ...
    {
      "name": "odi_unilib_mlt",
      "type": "double",
      "size": [
        1
      ],
      "units": "hr",
      "fill": "-1.0e+31",
      "description": "Magnetic local time calculated with UNILIB",
      "label": [
        "MLT"
      ]
    }
  ],
  "startDate": "2025-08-19T09:00Z",
  "stopDate": "2050-01-01T00:00Z",
  "cadence": "PT1M30S",
  "description": "MTG-S1/NGRM integral electron and differential proton fluxes (estimated using geometric factors derived with the Bow-Tie method), position, velocity and magnetic coordinates. MTG-S1 is designated to become Meteosat-13 after commissioning in geostationary orbit at 0°.",
  "resourceID": "spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1",
  "contactID": "spase://SSA/Person/SSCC.Helpdesk"
}

🔝 Go to top

Get data from a dataset

In this example, we use the /data endpoint to request data from the MTG-S1/NGRM integral electron and differential proton fluxes dataset (dataset id spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1) for a 5 minute period (on 25/03/2026 starting at 12:00:00 UTC until 12:05:00 UTC) and requesting only the 3 parameters displayed in the above example (utc,feio_1,odi_unilib_mlt). We first request the data in json format.

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
'https://swe.ssa.esa.int/hapi/data?dataset=spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1&parameters=utc,feio_1,odi_unilib_mlt&start=2026-03-25T12:00:00Z&stop=2026-03-25T12:05:00Z&format=json'

Response (in pretty print):

{
  "HAPI": "3.0.0",
  "status": {
    "code": 1200,
    "message": "OK"
  },
  "format": "json",
  "parameters": [
    {
      "name": "utc",
      "type": "isotime",
      "length": 24,
      "size": [
        1
      ],
      "units": "UTC",
      "fill": null,
      "description": "Timestamp in coordinated Universal Time (UTC)",
      "label": [
        "Time"
      ]
    },
    {
      "name": "feio_1",
      "type": "double",
      "size": [
        1
      ],
      "units": "cm^-2 s^-1 sr^-1",
      "fill": "-1.0e+31",
      "description": "Omnidirectional integral electron flux.\nFluxes were obtained from L0 counts using geometric factors derived with the Bow-Tie method.",
      "label": [
        "Integral electron flux (>0.15 MeV)"
      ]
    },
    {
      "name": "odi_unilib_mlt",
      "type": "double",
      "size": [
        1
      ],
      "units": "hr",
      "fill": "-1.0e+31",
      "description": "Magnetic local time calculated with UNILIB",
      "label": [
        "MLT"
      ]
    }
  ],
  "startDate": "2025-08-19T09:00Z",
  "stopDate": "2050-01-01T00:00Z",
  "cadence": "PT1M30S",
  "description": "MTG-S1/NGRM integral electron and differential proton fluxes (estimated using geometric factors derived with the Bow-Tie method), position, velocity and magnetic coordinates. MTG-S1 is designated to become Meteosat-13 after commissioning in geostationary orbit at 0°.",
  "resourceID": "spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1",
  "data": [
    [
      "2026-03-25T12:00:40.067Z",
      744958.0,
      11.6639
    ],
    [
      "2026-03-25T12:02:10.067Z",
      733622.0,
      11.6887
    ],
    [
      "2026-03-25T12:03:40.067Z",
      736119.0,
      11.7135
    ]
  ],
  "contactID": "spase://SSA/Person/SSCC.Helpdesk"
}

We can also request the same data but in CSV format and also include a header line with the parameter names on top:

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
'https://swe.ssa.esa.int/hapi/data?dataset=spase://SSA/NumericalData/D3S/d3s_mtgs1_ngrm_science_ep_l1_bt_v1&parameters=utc,feio_1,odi_unilib_mlt&start=2026-03-25T12:00:00Z&stop=2026-03-25T12:05:00Z&format=csv&include=header'

Response:

#utc,feio_1,odi_unilib_mlt
Time,Integral electron flux (>0.15 MeV),MLT
2026-03-25T12:00:40.067Z,744958.0,11.6639
2026-03-25T12:02:10.067Z,733622.0,11.6887
2026-03-25T12:03:40.067Z,736119.0,11.7135

🔝 Go to top