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.

Was this article useful? Yes No

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

Was this article useful? Yes No

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 the MMSI number prefixed by mmsi_

For the MMSI 311012100, the vessel id is "mmsi_311012100" , and the URL used to request the ships historical positions becomes :

https://ais.spire.com/vessels/mmsi_311012100/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/mmsi_311012100/positions?limit=5000&timestamp_after=2022-10-31T00:00:00&timestamp_before=2022-11-20T23:59:59

Was this article useful? Yes No

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/mmsi_220417000/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/mmsi_220417000/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

Was this article useful? Yes No

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: 000000000 – 999999999
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)

Was this article useful? Yes No