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 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 https://ais.spire.com/vessels/positions
If your API token is shorter like this
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
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
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:
"name": "EMMA MAERSK",
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 https://drive.google.com/drive/folders/1EadxAX224eUh_a8JD58PElmPHzxi55PP?usp=sharing
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.