Search Open menu

Historical Positions API

The Historical Positions API allows the retrieval of all historical positions for a specific vessel; and either from the beginning of the archive, or within a specified time window.

Available positions include Spire Satellite and Terrestrial AIS history from 2018-12-07; Dynamic AIS™ is included from 2020-03-25 (available only for Premium users with D-AIS™).

 

Download response samples and test programs

  • Example output from the API in json format
  • The output converted to CSV format for easy analysis
  • The log file of a program to call the API to show request durations.
  • A plot of the track from the data returned
  • The sample python program used to call the Vessels API to get the Spire vesselid for the vessel and then call the Historical Positions API.
  • A sample parameter file to use the sample program

Access on Google Drive

Note: The python code provided is unsupported and the quality not guaranteed. But is intended to demonstrate how the API can be used.

Using the API

To request all historical positions for a vessel, simply call the url with the vessel ID without specifying a time period as below

https://ais.spire.com/vessels/<VESSEL_ID>/positions?limit=5000

This unlimited call will of course return many rows of data and results will be provided in pages using the next and previous pagination system as used for the Vessels API.

 

For legacy reasons, there are 2 possible URLs to use for the Historical Positions API. If your API token is long like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21ldiI6eyZJpcW6IjU0RCIsIm5hbWUiOiJPY2VhbiBNaW5kIiwidXVpZCI6IjU0MCJ9LCJpc3MiOiJzCglyYs5jb28iLCJpYXQiOjE1NjE1NjQzOTR9.v3Z3_zy15DxhmjF06nXa88ZdkiXAQEa9R3t7UCxXJI

then use the base url:

https://ais.spire.com/vessels/<VESSEL_ID>/positions

If your API token is shorter like this

xGaYNmRYGV3fuD7w0pdPi2FkMlcQ4lNM

then use the base url:

https://api.sense.spire.com/vessels/<VESSEL_ID>/positions

Filtering by specific vessel

It is required to request historical positions for one specific vessel at a time. The request uses the Spire internal vessel id which is found by querying the vessel through the Vessels API or Maritime 2.0 Vessels query.

In the Vessels API, the first item returned in each data record is the Spire internal vessel id as shown below:

{
    "paging": {
        "limit": 100,
        "total": 1,
        "next": "dGltZT0xNTExMzA4NjUxLjAwNjAzMSxpZD02MjNiNTVmMC0yNjQ1LTQ0ODYtOTBhOC05NjI2ZGI1MGI0Mjg="
    },
    "data": [
        {
            "id": "7914a1a6-f178-303d-a93c-fa404a9d7dd1",
            "name": "EMMA MAERSK",
            "mmsi": 220417000,
            "imo": 9321483,
            "call_sign": "OYGR2",
            "ship_type": "Cargo",
            "class": "A",
            "flag": "DK",
            "length": 399,
            "width": 56,
(...)

For the ship above (Emma Maersk), the vessel id is "7914a1a6-f178-303d-a93c-fa404a9d7dd1" , and the URL used to request the ships historical positions becomes thus:

https://ais.spire.com/vessels/7914a1a6-f178-303d-a93c-fa404a9d7dd1/positions?limit=5000

…and finally to request this ships historical positions in a specific time period as above becomes this:

https://ais.spire.com/vessels/7914a1a6-f178-303d-a93c-fa404a9d7dd1/positions?limit=5000&timestamp_after=2019-07-08T08:00:00%2B05:00&timestamp_before=2019-07-08T12:00:00%2D05:00

Filtering by time

There are 2 time filter parameters that can be used with the Historical Positions API:

timestamp_aftertimestamp
Timestamp of the start of the time window for which position history is being requested.
Timestamps are specified in the format YYYY-MM-DDTHH:MI:SS[[+-]hh:mm]
timestamp_beforetimestamp
Timestamp of the end of the time window for which position history is being requested.
Timestamps are specified in the format YYYY-MM-DDTHH:MI:SS[[+-]hh:mm]

The optional timezone offset, if not specified, means that the timestamps are taken as UTC values. For example:

2019-07-08:12:00:00 specifies midday the 8th July 2019 UTC

2019-07-08:12:00:00+02:00 specifies midday the morning of 8th July 2019 UTC+3, IE CEST.

2019-07-08:12:00:00-05:00 specifies midday the 8th July 2019 UTC-5, IE EST.

So timezone offsets are required to specify time windows in a users local time.

Note however that when specifying the timezone offset to the API the + and i for the actual API call need to be encoded: + is coded as %2B and  - is coded as %2D .

 

Examples

All positions for vessel between midday and 5pm CEST

https://ais.spire.com/vessels/7914a1a6-f178-303d-a93c-fa404a9d7dd1/positions?limit=5000&timestamp_after=2019-07-08T12:00:00%2B02:00&timestamp_before=2019-07-08T17:00:00%2B02:00

All positions for vessel between 8am and midday EST

https://ais.spire.com/vessels/7914a1a6-f178-303d-a93c-fa404a9d7dd1/positions?limit=5000&_flags_on=historical_positions&timestamp_after=2019-07-08T08:00:00%2B05:00&timestamp_before=2019-07-08T12:00:00%2D05:00

Available response fields

vesselstring
Spire vessel API link with unique id used to reference the ships in the Spire database
idstring
Unique identifier of the position message in the Spire database
mmsiinteger
Vessel Maritime Mobile Service Identity. Possible values: 000000000999999999
timestamptimestamp
ISO 8601 formatted timestamp of position message collection in UTC at the time of broadcast
created_atdate
ISO 8601 formatted timestamp in UTC of the time the vessel record was created
geometrygeometry
Vessel position coordinates represented in GeoJSON
headingnumber
Vessel true heading in degrees. Possible values:0 - 359 degrees, 511 (not available)
speednumber
Vessel speed over ground represented in knots. Possible values: 0 - 102.2 knots, 102.3 (not available)
rotnumber
Vessel rate of turn. Possible values: -127 - 127; -128 (not available)
collection_typestring
How the data was captured. Possible values: satellite, terrestrial, or dynamic
maneuverinteger
Vessel maneuver code Valid values: 0 (not available; default), 1 (not engaged in special maneuver), 2 (engaged in special maneuver)
coursenumber
Vessel course over ground in degrees. Possible values: 0 - 359.9 knots, 360.0 (not available)