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.


Available Data

For premium users the available positions archive is the Spire Satellite and Terrestrial AIS history from 2018-12-07

Dynamic AIS is included in the positions archive from 2020-03-25 (Available only for Premium users with DAIS)


Historical Positions API URL

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 (deprecated)

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


Filtering Historical Positions For A Vessel that has Changed MMSI

Occasionally Vessels change the MMSI number that they use as their identifier in AIS messages. This happens when the vessel changes flag registration as the MMSI (and call sign) are issued by the flag register. 

When this happens Spire Vessels API has multiple records for the vessel. One or each of the MMSI numbers that have been used to report the vessels positions in AIS. Each Vessel record has a different ID number that must be passed to the Historical Positions API to retrieve the position history reported with each MMSI.

An example of this is Vessel with IMO number 9105994 

This call to Vessels API shows that querying on the IMO number returns 3 records.


    "paging": {

        "limit": 100,

        "total": 3,

        "next": "dGltZT0xNjEzNDY0MTE5LjA5OTI0NyxpZD00ZDJiN2U1Yi1iZmJhLTU3MjUtYjJhYS1kZDAzMjczOWM3OGI="



The 3 historical records of the vessel returned by the Vessels API are shown here 

Spire Sense Vessels API Results:
## First instance of IMO 9105994. Note the last update was 2017-06-19

    "data": [
           "id": "5413a402-a1e8-46eb-bc45-3ef0eb9a538a",
           "name": "NE CIN",
           "mmsi": 485981008,
           "imo": 9105994,
           "call_sign": "VZMI7",
           "ship_type": "Cargo",
           "class": "A",
           "flag": null,
           "length": 199,
           "width": 57,
           "created_at": "2017-09-06T01:53:30.268258+00:00",
            "updated_at": "2017-09-06T01:53:10.841804+00:00",
           "static_updated_at": "2017-09-06T01:53:10.841804+00:00",
            "position_updated_at": "2017-06-19T11:23:29.679777+00:00",
           "last_known_position": {
           "timestamp": "2017-06-18T14:06:35+00:00",

 The first instance of this vessel will not be included in the Historical Positions API results because the API only returns AIS position history from December 2018 onwards.

The 2nd instance of the vessel

## Second instance of IMO 9105994. Note the last update was 2021-02-16        
           "id": "29095064-3231-4987-80fa-72a8e460877e",
           "name": "VASI STAR",
           "mmsi": 477592400,
           "imo": 9105994,
           "call_sign": "VRMI7",
           "ship_type": "Cargo",
           "class": "A",
           "flag": "HK",
           "length": 184,
           "width": 25,
           "created_at": "2017-11-22T01:53:28.685265+00:00",
           "updated_at": "2021-02-16T06:17:14.950119+00:00",
            "static_updated_at": "2021-02-09T06:22:59+00:00",
           "position_updated_at": "2021-02-16T06:17:14.950119+00:00",
           "last_known_position": {
               "timestamp": "2021-02-16T06:16:26+00:00",

The AIS position history for this instance of the vessel will be returned from December 2018 and can be retrieved using the ID in bold above (29095064-3231-4987-80fa-72a8e460877e)

and the URL used to request the ships historical positions becomes this:×tamp_after=2018-12-01T00:00:00


The 3rd instance of the vessel

## Third instance of IMO 9105994. Note the vessel was created on 2021-02-16 
## when the new MMSI was first received       
           "id": "4d2b7e5b-bfba-5725-b2aa-dd032739c78b",
           "name": "VASI STAR",
           "mmsi": 636020646,
           "imo": 9105994,
           "call_sign": "5LAA3",
           "ship_type": "Cargo",
           "class": "A",
           "flag": "LR",
           "length": 184,
           "width": 25,
           "created_at": "2021-02-16T08:28:39.099247+00:00",
           "updated_at": "2021-04-12T13:57:16.977003+00:00",
           "static_updated_at": "2021-04-06T19:46:03+00:00",
           "position_updated_at": "2021-04-12T13:57:16.977003+00:00",
           "last_known_position": {
               "timestamp": "2021-04-12T13:56:42+00:00",

The API call to request the AIS position history for the current, most recent and 3rd instance of the vessel becomes this×tamp_before=2021-03-16T00:00:00×tamp_after=2021-02-16T00:00:00


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