Default API Behavior

Messages API

Given no specific arguments, the Messages API returns timestamp , msg_id , nmea  and id fields for 20000 AIS messages received within the past three hours:

GET https://ais.spire.com/messages
{
    "timestamp": "2018-05-15T20:56:21+00:00",
    "msg_id": "1526417781_413823016",
    "nmea": "!AIVDM,1,1,,B,B6:ah:00:j4qlj4?7IQvIUN021Mk,0*5E",
    "id": "cf1fde8c-a619-411e-8a69-1209b1ae5872"
}

To access all of the other decoded AIS fields, pass the fields parameter as set to decoded :

GET https://ais.spire.com/messages?fields=decoded
{
    "msg_type": 1,
    "msg_id": "1526405953_431704520",
    "course": 0.6,
    "collection_type": "satellite",
    "nmea": "!AIVDM,1,1,,A,16Ke9j701iHQ@DQnbtL01P<40000,0*22",
    "rot": 0,
    "id": "08c2b99c-ac70-40bf-86cc-278ca32c6771",
    "speed": 11.3,
    "source": "FM50",
    "latitude": -16.3036,
    "type": 1,
    "accuracy": 0,
    "status": 7,
    "maneuver": 0,
    "timestamp": "2018-05-15T17:39:13+00:00",
    "mmsi": 431704520,
    "flag": "Japan",
    "created_at": "2018-05-15T21:06:08.215187+00:00",
    "msg_description": "position",
    "longitude": -104.58344,
    "flag_short_code": "JP",
    "position": {
        "type": "Point",
        "coordinates": [
            -104.58344,
            -16.3036
        ]
    },
    "heading": 6
}

Vessels API

If no arguments are provided, the Vessels API returns 100 vessel records:

GET https://ais.spire.com/vessels
{
    "id": "b6ed4851-c629-4f0a-9c90-9e1874ced280",
    "name": "ELENI D",
    "mmsi": 636014651,
    "imo": 9577410,
    "call_sign": "A8VQ4",
    "ship_type": "Cargo",
    "class": "A",
    "flag": "LR",
    "length": 196,
    "width": 33,
    "ais_version": 0,
    "created_at": "2017-08-11T19:24:21.193385+00:00",
    "updated_at": "2018-05-21T16:20:09.824959+00:00",
    "last_known_position": {
        "timestamp": "2018-05-21T13:36:56+00:00",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -42.14087,
                -25.19044
            ]
        },
        "heading": 190,
        "speed": 8.2,
        "rot": 0,
        "accuracy": null,
        "collection_type": "satellite",
        "draught": null,
        "maneuver": 0,
        "course": 187.4
    },
    "most_recent_voyage": {
        "eta": "2018-04-25T21:00:00+00:00",
        "destination": "NOUAKCHOT"
    },
    "predicted_position": {
        "timestamp": "2018-05-21T17:51:05+00:00",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -42.2236022408,
                -25.7641057924
            ]
        },
        "speed": 8.2,
        "course": 187.4,
        "confidence_radius": 50.3796
    },
    "general_classification": "Merchant",
    "individual_classification": "Bulk Carrier",
    "gross_tonnage": "0",
    "lifeboats": null,
    "person_capacity": null,
    "navigational_status": null
}

Pagination

All API responses above a certain size get "paginated" to make the response handling manageable. The default page limit for the Messages and Vessels APIs is 20000 messages and 100 vessels respectively:

Messages API

"paging": {
    "limit": 20000,
    "since": "MjAxOC0wNS0xNSAyMToxNzoyOS44Nzc1MjQrMDA6MDA=",
    "actual": "20000+"
}
[messages follow ...]

Vessels API

"paging": {
    "limit": 100,
    "total": 312511,
    "next": "dGltZT0xNTAyNTc5MzE1Ljc3NTU4NSxpZD1jNGExY2U1ZS04MzA3LTRjZGQtODg3ZS1lOTBjNmVlNWY0MWI="
}
[vessels follow ...]

Custom Limits

As mentioned above, requests made to Spire Sense APIs may lead to tens or hundreds of thousands of available results across multiple pages. Though each API has a default limit  parameter, this can be customized to adjust the amount of data per page.

To request a 100 messages from the Messages API:

GET https://ais.spire.com/messages?fields=decoded&limit=100
  • Maximum limit for the Messages API is the default 20000 .
  • Maximum limit for the Vessels API is 1000 .

Cursors

Spire makes millions of AIS messages available to you every day in a constantly updating feed. This near real-time nature and volume of data constantly being added to the feed means that typical "pages" don't work very well.

Cursors help out with this. Like a bookmark, they let you quickly request data from where you last left off.

Messages API

Let's say you request 2 messages:

GET https://ais.spire.com/messages?fields=decoded&limit=2

In the following response, the since  parameter nested within paging is your cursor for the following page of results.

{
    "paging": {
        "limit": 2,
        "since": "MjAxOC0wNS0xNiAyMjowNTowMy42ODQ3MDArMDA6MDA=",
        "actual": "2+"
    },
    "data": [
        {
            "msg_type": 3,
            "msg_id": "1526508302_220298000",
            "course": 104,
            "collection_type": "terrestrial",
            "nmea": "!AIVDM,1,1,,B,33B5s40015PBSaHMgme443:40>`<,0*34",
            "rot": 0,
            "id": "72c917a1-34f2-4c9c-8813-45eabe571b8b",
            "speed": 6.9,
            "latitude": 51.9875,
            "type": 3,
            "accuracy": 1,
            "status": 0,
            "maneuver": 0,
            "timestamp": "2018-05-16T22:05:02+00:00",
            "mmsi": 220298000,
            "flag": "Denmark",
            "created_at": "2018-05-16T22:05:03.684700+00:00",
            "msg_description": "position",
            "longitude": 4.0538333333,
            "flag_short_code": "DK",
            "position": {
                "type": "Point",
                "coordinates": [
                    4.0538333333,
                    51.9875
                ]
            },
            "heading": 101
        },
        {
            "msg_type": 1,
            "msg_id": "1526508301_205465690",
            "course": 0,
            "collection_type": "terrestrial",
            "nmea": "!AIVDM,1,1,,B,133t`FPP00PE7l`MU1bh0?v2R<1T,0*0B",
            "rot": -128,
            "id": "c5bbccef-34e5-47a3-a561-518c8f61ed08",
            "speed": 0,
            "latitude": 51.6922316667,
            "type": 1,
            "accuracy": 1,
            "status": 0,
            "maneuver": 1,
            "timestamp": "2018-05-16T22:05:01+00:00",
            "mmsi": 205465690,
            "flag": "Belgium",
            "created_at": "2018-05-16T22:05:03.684700+00:00",
            "msg_description": "position",
            "longitude": 4.61422,
            "flag_short_code": "BE",
            "position": {
                "type": "Point",
                "coordinates": [
                    4.61422,
                    51.6922316667
                ]
            },
            "heading": 511
        }
    ]
}

To fetch the next page of messages, include the since parameter in your following API call:

GET https://ais.spire.com/messages?fields=decoded&limit=2&since=MjAxOC0wNS0xNiAyMjowNTowMy42ODQ3MDArMDA6MDA=

And so forth...

Vessels API

If you request information from 2 vessels:

GET https://ais.spire.com/vessels?limit=2

The next  parameter within paging is the cursor to the following page of results:

{
    "paging": {
        "limit": 2,
        "total": 312365,
        "next": "dGltZT0xNTAyNDc3Mzg2LjQzNDIxNCxpZD05NjE2OTdhMy0yZmM1LTRiOWYtOWJiMS03OTI3ZTkzNDBlZWY="
    },
    "data": [
        {
            "id": "b4d14520-9652-46a9-a8f5-70d8eb4285b8",
            "name": "SAN HANG JUN 3",
            "mmsi": 412043340,
            "imo": null,
            "call_sign": null,
            "ship_type": null,
            "class": "B",
            "flag": "CN",
            "length": null,
            "width": null,
            "ais_version": 0,
            "created_at": "2017-08-11T18:34:23.904133+00:00",
            "updated_at": "2018-05-17T14:36:15.667233+00:00",
            "last_known_position": {
                "timestamp": "2018-05-17T14:35:44+00:00",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        118.4675,
                        24.52898
                    ]
                },
                "heading": 511,
                "speed": 0.1,
                "rot": null,
                "accuracy": null,
                "collection_type": "terrestrial",
                "draught": null,
                "maneuver": null,
                "course": 0
            },
            "most_recent_voyage": {
                "eta": null,
                "destination": null
            },
            "predicted_position": {
                "timestamp": "2018-05-17T18:21:05+00:00",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        118.4675,
                        24.5352355042
                    ]
                },
                "speed": 0.1,
                "course": 0,
                "confidence_radius": 43.9973
            },
            "general_classification": "All Other Activities",
            "individual_classification": "Unspecified",
            "gross_tonnage": "34.0",
            "lifeboats": null,
            "person_capacity": null,
            "navigational_status": null
        },
        {
            "id": "961697a3-2fc5-4b9f-9bb1-7927e9340eef",
            "name": "JOHAN PIONEER 2",
            "mmsi": 533636000,
            "imo": 9409211,
            "call_sign": "9 WGN 5",
            "ship_type": "Tug",
            "class": "A",
            "flag": "MY",
            "length": 34,
            "width": 10,
            "ais_version": 0,
            "created_at": "2017-08-11T18:49:46.434214+00:00",
            "updated_at": "2018-05-16T22:24:14.299384+00:00",
            "last_known_position": {
                "timestamp": "2018-05-16T16:08:24+00:00",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        89.55557,
                        22.57744
                    ]
                },
                "heading": 32,
                "speed": 0,
                "rot": -128,
                "accuracy": null,
                "collection_type": "satellite",
                "draught": null,
                "maneuver": 0,
                "course": 38.9
            },
            "most_recent_voyage": {
                "eta": "2018-04-21T15:00:00+00:00",
                "destination": "LUMUT/MALAYSIA"
            },
            "predicted_position": {
                "timestamp": null,
                "geometry": {
                    "type": "Point",
                    "coordinates": []
                },
                "speed": null,
                "course": null,
                "confidence_radius": null
            },
            "general_classification": "Merchant",
            "individual_classification": "Pusher/Tug",
            "gross_tonnage": "0",
            "lifeboats": null,
            "person_capacity": null,
            "navigational_status": "Moored"
        }
    ]
}

To fetch the next page of vessels, include the next parameter in your following API call:

GET https://ais.spire.com/vessels?limit=2&next=dGltZT0xNTAyNDc3Mzg2LjQzNDIxNCxpZD05NjE2OTdhMy0yZmM1LTRiOWYtOWJiMS03OTI3ZTkzNDBlZWY=

And so forth...

API Rate Limits

We recommend keeping the frequency of your API calls below 30 per minute. If you attempt to query one of the Spire Sense APIs more often than that, you may encounter the following error:

Spire API rate limit exceeded. Please limit your requests to 30 per minute to avoid future issues.

If you encounter this error, it should clear within about 30 seconds.

Related Content

Additional API Parameters

To learn more about available API parameters, check out Using API Filter Parameters.

The Last Page

Reached the last page of results and looking for strategies? Check out Keeping Up after the Last Page of Results.

Did this answer your question?