Using the Spire Maritime AIS TCP Feed V2

How to use the Spire Maritime AIS TCP feed V2.

This FAQ outlines how to use the Version 2 (V2) version of the Spire Maritime AIS TCP Feed. This replaces the V1 TCP stream. It is intended to be backwardly compatible with the V1 service but may require different authentication tokens. 

Slides comparing the TCP Stream to Messages API and details of the AIS stream NMEA format are available in PDF format here 

Connect to the Spire Sense TCP Server

To be able to use the Spire AIS TCP Service, an authorization token needed, which is used to authenticate the service.

Initiating the TCP Feed: Initiate Connection.

For TCP connections, client systems must open a TCP socket connection to the Spire service on the     Service Address :

using Port number: 56784.

To initiate the stream of messages, and initial authentication string must be sent as below:


Note: Depending on which system you are using, you might want to send a new line ‘\n’ to make sure that the token is sent in one piece directly

If connection is successful then the stream of AIS data in NMEA format will start as shown in the example below. This can also be used to test the connectivity on your side.

nc 56784

Above shows the service connection and the first 3 results of AIS messages being returned.

Possible initial delay.

Once your connection has been established, AIS messages should begin streaming into your client. Note: It can take up to 60 seconds for the TCP server to start up a new stream after sending your token. 

Recommended Reconnection Strategy

The TCP server should keep your connection alive indefinitely and send keep-alives every 15 minutes to your client, however, exceptions still happen. Occasionally there might still be instances of unexpected disconnects to the TCP feed. In these cases, you can simply reconnect, re-authenticate with your token and the data stream will resume.

In order to minimize loss of data and impact on latency, we recommend setting up a reconnection method that automatically acts within an hour of any unexpected disconnect.

Interruptions Continue Where Left Off

The behaviour of the TCP service is to provide a continuous stream of AIS messages in the order that they are received by Spire systems. If the service stops, due to disconnection or client system problems, then if re-connecting within 7 days from disconnection, the stream of data will continue from the time of disconnection and no data will be missed.

If the service is disconnected for more multiple hours or days then it can cause a large backlog of now old data to be streamed before the service catches up to current time and entirely new messages are received. 

If the service is disconnected for more than 7 days then data will be streamed from the current time and only new messages are received.  In this situation please contact Spire Maritime sales engineering here to request a backfill of historical data that has been missed. 

Connection Lag

If your system is experiencing connection lag (ie. the data you are receiving is well behind real-time results as indicated by the unix timestamp [c:]), we recommend reviewing your system to see where scaling is necessary to cope with the increased data volume and speed from the TCP V2 feed. Once the system has been adjusted, use the Updating the Service Checkpoint section below to set the checkpoint to a specified time or to the latest message time (real-time).

Updating the Service Checkpoint

In the V2 TCP stream service it is possible to update the service checkpoint  that species where in the stream of data service will continue from.

Setting checkpoint to a specified time:

To reset your TCP stream service to start from a particular point in time, pass the authentication token string as normal followed by a date time string in the format YYYY-MM-DDTHH:MM:SS.MMMZ. Note the time must be in UTC (zulu time)

Example authentication to set the TCP stream checkpoint to a given time


Note the checkpoint  can be set up to 7 days in the past and times most be specified in UTC

example below

nc 56784

Above shows the service checkpoint reset request after which the connection is reset.
To stream data, connection must be established again


Setting checkpoint to the latest message time:

To reset your TCP stream service to start from a the time of the most recent message in your service, pass the authentication token string as normal followed by the label resetToLatest

Example authentication to set the TCP stream checkpoint to the latest message time


example below

nc 56784

Above shows the service checkpoint reset request after which the connection is reset.
To stream data, connection must be established again


Forced reconnect after updating the service checkpoint

After setting a checkpoint timestamp or the checkpoint reset label resetToLatest the TCP service will update the checkpoint and disconnect.

You will need to connect again and pass auth string as usual `A|T|<your-token>` to get the data from the new checkpoint.

Multipart messages

AIS message 5 is commonly received in multiple parts, generally 2 message sentences. Spire AIS stream v2 provides grouping tags as shown below. Optionally for users who require it, this feature may be disabled upon request to Spire Maritime sales engineering here 

An example of multi part AIS message 5 showing the NMEA compliant group tag


Sample TCP Stream results

Example TCP stream results

Understanding the AIS message stream format above 

group tag \g:1-2-5 and \g:2-2-5
Group tag has 3 parts X-Y-Z.
X is the fragment number
Y is the count of message fragments
Z is the sequence number that joins the fragments together

source tag \s indicating the AIS source of the received AIS message
Values are:
terrestrial for AIS received from terrestrial, land based, AIS receivers.
dynamic for AIS received from dynamic AIS, vessel based, AIS receivers.
<satellite id> for messages received from Spire satellites.
Note satellite id will be the NORAD ID of the satellite
or if the NORAD ID is not yet confirmed then the Spire satellite name

message timestamp and tags checksum \c:1601972308*58
message header !AIVDM
message sentence count 2
message sentence number 1 or 2
message number 5
AIS channel A or B
Encoded AIS data and checksum (the rest of the message record)

Example Python to connect

A simple python program for connecting to the Spire TCP service is available for testing from this Google Drive link

It can be called  in the following fashion (using a demo or client authentication token)

python test_tcp.txt 100 56784 2 <CLIENT AUTHENTICATION TOKEN>


python test_tcp.txt 100 56784 2 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6eyJpZCI6IjcxMSIsIm5hbWUiOiJTcGlyZSBUQ1AgREVNTyBET1ZFUiIsInV1aWQiOiI3MTEifSwiaXNzIjoic3BpcmUuY29tIiwiaWF0IjoxNTk1NDA0MTUxfQ.kOiZqAYH2-uY6EJZHLKwuqyMhP763CttvFm8DuQZQW8

Sample Results

python3 t
est_tcp.txt 100 56784 2 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6eyJpZCI6IjcxMSIsIm5hbWUiOiJTcGlyZSBUQ1AgRE
Program Start Time: 2020-07-22T09:55:43+02:00
server set to parameter value:
Run TCP client for 2 minutes
Debug set to default of False - False
Parameter Debug = : False
Using API Token from parameters
Using API Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6eyJpZCI6IjcxMSIsIm5hbWUiOiJTcGlyZSBUQ1AgREVNTyBET1ZFUiIsInV1aWQiOiI3MTEi
About to try connecting to:
Server: on port: 56784

Writing text data stream to file test_tcp.txt20200722-075543.txt
Writing nmea data stream to file test_tcp.txt20200722-075543_nmea.txt
Setting job message limit : 100
program has run for 0.0 minutes. 20200722-075546 Last Minute captured 1 records.
Stopping as max_records number reached: 100
Stopping as max_records number reached: 100
Stopped after receiving 100 messages 100
API Processing ran from 20200722-075543 to 20200722-095546 received 100 lines of results

Program run from 20200722-075543 to 20200722-095546 took (0.0, 2.779322) minutes

Start time as unix time: 1595397343.0
End time as unix time: 1595397346.0
Elapsed time in seconds: 3

wc -l test_tcp.txt20200722-075543_nmea.txt
100 test_tcp.txt20200722-075543_nmea.txt

Showing the captured results

head -5 test_tcp.txt20200722-075543_nmea.tx


For further questions or support please submit questions to the Spire Sales Engineering team using our client web support form here