SHT Rest API

The SHT REST-API provides a programmatic interface to the information generated and used by the The Timeline Tool.

Overview

The SHT Rest API allows you to retrieve most of the information provided by SHT in order to generate your own graphics or analysis derived from that information.

Accessibility

The REST-API entry point is the following URL: https://juicesoc.esac.esa.int/rest_api

The full documentation of the API is available at the API Documentation. Please note that this documentation is not very descriptive and might not be easy to understand by somebody who is not familiar with REST-API protocols.

Practical examples of REST-API usage are provided hereunder.

We recommend to use the free tool Postman as a graphical interface for REST-APIs

Working with the REST-API

There are several HTTP entry points methods for REST-APIs. The most general one is GET with which we ask for a piece of information and we simply get it back. There is also POST with which we send an input and the REST-API will provide an output product (this is used by the Pointing Tool REST-API, more details in Pointing Tool/AGM REST-API). With PUT we can modify a value within SHT and with DELETE, well, delete it. These last two commands will be rarely used by us (if ever).

A trick in order to better understand each query to the REST-API is to use the Web browser in developer mode in such a way that we can obtain the different queries that the SHT web app performs to the SHT REST-API.

Basic GET request

A basic request that we can exercise with the SHT REST-API is to get the trajectory information for a given trajectory (crema). For crema 5.0 We do so by sending the following request:

https://juicesoc.esac.esa.int/rest_api/trajectory/CREMA_5_0

For example we can use Python in order to help us to get the mission phases of the trajectory:

import requests
import json

url = f'https://juicesoc.esac.esa.int/rest_api/trajectory/CREMA_5_0'

response = requests.get(url)
trajectory = response.json()
phases = trajectory.get('phases')

print(json.dumps(phases, indent=4))

yelding:

[
    {
        "name": "Approach and first ellipse",
        "mnemonic": "CREMA_5_0_JUPITER_PHASE_1",
        "start": "2031-01-19T19:14:21Z",
        "end": "2032-02-08T23:05:31Z"
    },
    {
        "name": "Energy reduction",
        "mnemonic": "CREMA_5_0_JUPITER_PHASE_2",
        "start": "2032-02-08T23:05:32Z",
        "end": "2032-06-25T12:23:23Z"
    },
    {
        "name": "Europa flybys",
        "mnemonic": "CREMA_5_0_JUPITER_PHASE_3",
        "start": "2032-06-25T12:23:23Z",
        "end": "2032-07-24T07:02:19Z"
    },
    {
        "name": "High-latitude",
        "mnemonic": "CREMA_5_0_JUPITER_PHASE_4",
        "start": "2032-07-24T07:02:19Z",
        "end": "2033-08-18T09:43:28Z"
    },
    {
        "name": "Low energy",
        "mnemonic": "CREMA_5_0_JUPITER_PHASE_5",
        "start": "2033-08-18T09:43:28Z",
        "end": "2034-12-19T00:00:00Z"
    }
]

Advanced GET request

An example of a more advanced GET request is the one to obtain a time series from SHT. The request for the geometry series is not as simple, but it can be easily obtained by extracting the information from the Web browser in developer mode.

The syntax is as follows:

https://juicesoc.esac.esa.int/rest_api/series/?body={"start":"2031-09-01T00:00:00Z","end":"2035-09-01T00:00:00ZZ","trajectory":"CREMA_5_0","series":"sp_body_dist"}

It is easier to see the request, after the ?body= as a pretty JSON snippet:

{
    "start": "2031-09-01T00:00:00Z",
    "end": "2035-09-01T00:00:00ZZ",
    "trajectory": "CREMA_5_0",
    "series": "sp_body_dist"
}

Again as before we can easily perform the query with Python:

import requests
import json

request = '{"start":"2031-09-01T00:00:00Z","end":"2035-09-01T00:00:00ZZ","trajectory":"CREMA_5_0","series":"sp_body_dist"}'
url = f'https://juicesoc.esac.esa.int/rest_api/series/?body={request}'

response = requests.get(url)
series = response.json()

The resulting format of the time series is not very convenient. An example on how to plot quantity is provided in the following Python Notebook. Find more about JUICE SOC Jupyter Notebooks in Jupyter Notebooks.