Push Position API

The current appendix aims at describing PLANET push position API. This API allows the integration of vehicle positions in PLANET system from third party applications.

Pre-requisites

The API calls are subject to authentication. This means a login/password is required in PLANET system to be able to perform API calls.

To be able to push a position for a given vehicle using the API, here are some constraints:

  • the vehicle ident must exists in PLANET system.

  • the vehicle must belong to a mission.

  • the vehicle must be virtual.

Note

It is highly recommanded to create a dedicated login/password to make API calls.

The Admin section explains how to create a virtual vehicle and attach it to a mission.

API Description

Pushing a position is performed via a POST request.

An authentication is required to perform the push position POST. There are two possible authentication mechanisms: either basic or token.

Authentication

Basic Authentication

With basic authentication, the username and password must be provided in the header of each POST request.

The POST request headers must contain an Authentication field as follows:

Authentication: Basic {Base64String}

where {Base64String} stands for the Base64 encoding of username:password string.

Token Authentication

This authentication procedure consists of a POST request on a login URL to retrieve an authentication token that will be injected in the header of the push position API call.

Login POST request:

curl -H 'Content-Type: application/json' --request POST --data '{"username":"dumy","password":"dumy"}' https://{CLIENT_ID}.atmosphere.aero/api/v1/auth/token/login/

The Content-Type must be defined in the request headers (set to application/json).

The username and password fields of the JSON payload have to be replaced with proper values.

The {CLIENT_ID} has te be replaced by the appropriate value. (see Access section).

Login POST response:

{"auth_token":"6dcee5f0aada9fdeecacfb2a37b5c3952f11421b"}

Position Push

Depending on authentication method, the push position is performed as follows:

Push position POST with Basic Authentication:

curl -H 'Content-Type: application/json' -H "Authorization: Basic {Base64String}" --request POST --data '{"source": "DUMY", "latitude": 44,"longitude": 1.4, "date": "2022-05-24T15:41:16Z", "properties":{"true_heading":7.0,"ground_speed":222.0,"gps_msl_alt":61.0 }}' https://{CLIENT_ID}.atmosphere.aero/api/v1/telemetry/{VEHICLE_ID}/position

where {Base64String} must be replaced properly.

OR

Push position POST with Token Authentication:

curl -H 'Content-Type: application/json' -H "Authorization: Token {AuthenticationToken}" --request POST --data '{"source": "DUMY", "latitude": 44,"longitude": 1.4, "date": "2022-05-24T15:41:16Z", "properties":{"true_heading":7.0,"ground_speed":222.0,"gps_msl_alt":61.0 }}' https://{CLIENT_ID}.atmosphere.aero/api/v1/telemetry/{VEHICLE_ID}/position

where {AuthenticationToken} must be replaced properly.

The {VEHICLE_ID} in the URL must be replaced with the PLANET ident of the concerned vehicle.

The data must be a valid JSON string with the following fields:

  • source (mandatory): a string that defines the source of the position. No pre-requisite on that string but may always remain the same if the source does not change.

  • latitude (mandatory): latitude of the vehicle in degrees.

  • longitude (mandatory): longitude of the vehicle in degrees.

  • date (optional): if not set, the server will tag the position with the current date, otherwise it will used the provided date. The date (UTC) field must follow the iso-8601 format.

  • properties (optional): a dictionnary of optional properties associated to the pushed position. A true_heading should be provided to be able to orientate the vehicle icon on the map. All the properties can also be added to the HUD box (see HUD section) and will be displayed in the telemetry view (see Telemetry section).

Note

When using the Token Authentication method, the POST login request to get the token may only be performed once at initialisation (i.e. not before each Push position POST). Ifever the Push position POST returns an ‘Invalid Token’ reply, then calling the POST login request will be required again to get a new valid token.

Errors

Possibles errors returned by the POST are:

  • HTTP_400_BAD_REQUEST: {“error”: “Vehicle does not exist”}

  • HTTP_400_BAD_REQUEST: {“error”: “PLID must belong to a mission”}

  • HTTP_400_BAD_REQUEST: {“error”: “PLID must be virtual”}

  • HTTP_400_BAD_REQUEST: {“error”: “Missing source field”}

  • HTTP_400_BAD_REQUEST: {“error”: “Missing longitude field”}

  • HTTP_400_BAD_REQUEST: {“error”: “Missing latitude field”}

  • HTTP_403_FORBIDDEN: {“error”: “Must be superuser or member of mission’s customer”}

  • HTTP_403_FORBIDDEN: {“detail”:”Invalid token.”}