The Last Page

In this article we explain how cursors can be used to navigate through paginated responses of results.

Messages API

The since cursor turns through recent messages:

GET https://ais.spire.com/messages?fields=decoded
"paging": {
    "limit": 20000,
    "since": "MjAxOC0wNS0xNyAyMzozNzowNC4yODI2NDUrMDA6MDA=",
    "actual": "165"

However, after the last page is reached, the since cursor will remain the same value and actual results will be 0 .

"paging": {
    "limit": 20000,
    "since": "MjAxOC0wNS0xNyAyMzozNzowNC4yODI2NDUrMDA6MDA=",
    "actual": "0"
}

If you're querying for recent AIS messages (the default behavior), this response indicates you've reached the end of the feed. For this moment there are no new AIS messages to ingest.

Vessels API

The next cursor turns through each returned page of vessels:

"paging": {
    "limit": 100,
    "total": 312363,
    "next": "dGltZT0xNTAyNTc5MzE1Ljc3OTYxNyxpZD1kNmYyZjMxYS1kNWQyLTRmN2QtOWNkNS1lMGJkZjFmMDM4ZmE="
}

However, eventually, the last page is reached and no cursor is returned:

"paging": {
    "limit": 100,
    "total": 312363
}

This indicates that you've viewed the last vessel record within your results.

From here, we recommend switching to keeping up with live updates.

Fetch Live API Updates

Messages API

The Messages API primarily serves as a constantly updating feed. Once you've reached the last page, your API client should continue periodically fetching the since cursor. A change in the value for since indicates new messages are available.

Below, we have some output from our sample Python Live Messages API Client as it keeps up with live Messages API updates for reference:

Start Querying SPIRE Data...
https://ais.spire.com/messages?fields=decoded
20000 messages
{u'actual': u'20000+', u'since': u'MjAxOC0wNS0xNyAyMzo1Njo0Ni40MzczNjgrMDA6MDA=', u'limit': 20000}
https://ais.spire.com/messages?since=MjAxOC0wNS0xNyAyMzo1Njo0Ni40MzczNjgrMDA6MDA=&fields=decoded
6201 messages
{u'actual': u'6201', u'since': u'MjAxOC0wNS0xOCAwMDozNjozMy43ODQ3MDMrMDA6MDA=', u'limit': 20000}
https://ais.spire.com/messages?since=MjAxOC0wNS0xOCAwMDozNjozMy43ODQ3MDMrMDA6MDA=&fields=decoded
0 messages
{u'actual': u'0', u'since': u'MjAxOC0wNS0xOCAwMDozNjozMy43ODQ3MDMrMDA6MDA=', u'limit': 20000}
Waiting for 1 minute.
https://ais.spire.com/messages?since=MjAxOC0wNS0xOCAwMDozNjozMy43ODQ3MDMrMDA6MDA=&fields=decoded
162 messages
{u'actual': u'162', u'since': u'MjAxOC0wNS0xOCAwMDozNzozMy42Njk3MzUrMDA6MDA=', u'limit': 20000}
https://ais.spire.com/messages?since=MjAxOC0wNS0xOCAwMDozNzozMy42Njk3MzUrMDA6MDA=&fields=decoded
0 messages
{u'actual': u'0', u'since': u'MjAxOC0wNS0xOCAwMDozNzozMy42Njk3MzUrMDA6MDA=', u'limit': 20000}
Waiting for 1 minute. 

Vessels API

Once you've requested every vessel record of interest, the updated_after API parameter can be used to only request vessels from which we've recently received updated information. Let's say 2018-05-18T00:00:00 is the time at which the following request was made:

GET https://ais.spire.com/vessels/?ship_type=cargo

If you wanted to check for hourly updates, at 2018-05-18T01:00:00 , send the following request to fetch any cargo vessels with updates within the past hour:

GET https://ais.spire.com/vessels/?ship_type=cargo&updated_after=2018-05-18T00:00:00

At this point, turn through paginated results via next until you've reached the last page. Repeat again an hour later.

Did this answer your question?