Spire Sense Vessels, Historical Positions feature

Spire Sense Premium includes the option to use the historical positions API feature.
This allows retrieval of all historical positions either for a specific vessel or all vessels and either from the beginning of the archive or within a specified time window.

For premium users the available positions archive is the Spire AIS history back to
07-Dec-2018. 

Note: Spire operates 2 systems for configuring API access, to allow some legacy features and clients to be continued. This means that there are 2 possible URLs to use for the Historical Positions API
If your API token is long like this
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6eyZJpcW6IjU0MCIsIm5hbWUiOiJPY2VhbiBNaW5kIiwidXVpZCI6IjU0MCJ9LCJpc3MiOiJzCglyYs5jb20iLCJpYXQiOjE1NjE1NjQzOTR9.v3Z3_zy15DxhmjF06nXa88ZdkiXAQEa9R3t7UCxXJI

then use the base url https://ais.spire.com/vessels/positions

If your API token is shorter like this
xGaYNmRYGV3fuD7w0pdPi2FkMlcQ4lNM

then use the base url https://api.sense.spire.com/vessels/positions 

Extracting Historical Positions for all vessels

To request all historical positions for all vessels, simply call the url without specifying a time period or specific vessel as below 

https://ais.spire.com/vessels/positions?_flags_on=historical_positions&limit=5000

This unlimited call will of course return millions of rows of data and results will be provided in pages using the next and previous pagination system as used for the Vessels API. If you are not familiar with the pagination of Spire API results then see this article http://answers.spire.com/en/articles/1920292-keeping-up-after-the-last-page-of-results 

Filtering Historical Positions By Time

There are 2 time filter parameters that can be used with the historical positions API.

timestamp_after which takes a timestamp after which positions are required

timestamp_before which takes a timestamp before which positions are required

both timestamps are specified in the format YYYY-MM-DDTHH:MI:SS[[+-]hh:mm]
the optional timezone offset, if not specified means that the time stamps are taken as UTC values
Timestamp Examples:
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 
  • is coded as %2D

Sample API call to get all positions between midday and 5pm CEST
https://ais.spire.com/vessels/positions?limit=5000&_flags_on=historical_positions&timestamp_after=2019-07-08T12:00:00%2B02:00&timestamp_before=2019-07-08T17:00:00%2B02:00 

Sample API call to get all positions between 8am and midday EST
https://ais.spire.com/vessels/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

Filtering Historical Positions For A Specific Ship

It is possible to request historical positions for a specific ship but in the initial implementation it has to be requested using the Spire internal vessel id which is found by querying the vessel through the Vessels API.
It's not pretty but it works! 

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

Spire Sense Vessels API Results:
{
    "paging": {
        "limit": 100,
        "total": 1,
        "next": "dGltZT0xNTExMzA4NjUxLjAwNjAzMSxpZD02MjNiNTVmMC0yNjQ1LTQ0ODYtOTBhOC05NjI2ZGI1MGI0Mjg="
    },
    "data": [
        {
            "id": "623b55f0-2645-4486-90a8-9626db50b428",
            "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 

623b55f0-2645-4486-90a8-9626db50b428

and the URL used to request the ships historical positions becomes this:
** NOTE 10-July. notified that vessel_id will become a parameter option **

so this

https://ais.spire.com/vessels/623b55f0-2645-4486-90a8-9626db50b428/positions?_flags_on=historical_positions&limit=5000

becomes this specifying vessel_id as an API parameter

https://ais.spire.com/vessels/positions?_flags_on=historical_positions&limit=5000&vessel_id=623b55f0-2645-4486-90a8-9626db50b428

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

https://ais.spire.com/vessels/positions?_flags_on=historical_positions&limit=5000&vessel_id=623b55f0-2645-4486-90a8-9626db50b428&timestamp_after=2019-07-08T08:00:00%2B05:00&timestamp_before=2019-07-08T12:00:00%2D05:00


For further help contact info@spire.com

Did this answer your question?