Using the Historical Positions API

Using the Spire Sense Premium option historical positions API to retrieve historic positions for one or all ships.

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

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

then use the base url

If your API token is shorter like this

then use the base url 

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

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 

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 



Sample API call to get all positions between 8am and midday EST


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 


and the URL used to request the ships historical positions becomes this:

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


Sample Historical Positions API Results & Test Program

Sample of Vessels Historical Positions results and test programs are available to clients from this Google Drive folder

where you will find

1. Example output from the API in json format
2. The output converted to CSV format for easy analysis
3. The log file of a program to call the API to show request durations.
4. A plot of the track from the data returned
5. 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.
6. A sample parameter file to use the sample program
Note: The python code is unsupported and the quality not guaranteed. But is intended to demonstrate how the API can be used.

For further help use the developer support form or contact