JSON AIS.en

JSON AIS transmission protocol

This is a work-in-progress specification for passing parsed AIS data in human- and computer-readable JSON format. If you have ideas for this specification, please email Heikki Hannikainen, OH7LZB (hessu at hes dot iki dot fi).

This protocol is useful for transmitting AIS data between AIS receiver sites and live AIS database services, and also for transmitting AIS data between AIS database services which choose to trust each other and exchange data.

This specification was initially implemented by Lekkas Dimitris of marinetraffic.com, and documented by Heikki Hannikainen of aprs.fi. Additional feedback has been received from Tapio Sokura, OH2KKU.

Description of message structure

This document defines three levels of JSON messages.

First, after decoding the AIS packets they are encoded into AIS packet messages. They contain data from the AIS message itself.

Then, when a set of AIS packet messages are transmitted between two trusted servers, they are grouped in packet group messages per transmission path. The packet group message contains the path the packets have traveled so far, and an array of AIS packet messages. This is done to reduce network traffic - we will have a lot of packets having the same transmission path ('Receivingsite1', 'aprs.fi', 'marinetraffic.com'), so it is not necessary to transmit the path separately with each AIS packet message.

The packet group messages are then, optionally, enclosed in a transport message. The transport message contains identifiers for detecting that the received message is a valid JSON AIS message, and might at a later phase contain a protocol version number, if the protocol needs to be extended in a non-compatible way. The transport message can be used when packet group messages are transmitted over HTTP pushing/polling, but might not be necessary when a stream of packet group messages are transmitted over a persistent TCP connection, since the relevant handshaking information can be exchanged once when the connection is opened.

Message fields

Mandatory fields in all AIS packet messages

• msgtype
  • Integer. This is the type of the AIS message. 5 for ship the ship information packet, 1/2/3 for the position packet, which is sent more often.
• mmsi
  • Integer. This is the MMSI number of the ship.
• timestamp
  • The timestamp of the message - UTC, "MM/DD/YYYY HH:MM:SS". This should be, as accurately as possible, the time the AIS message was transmitted by the vessel. Some AIS messages might contain a GPS-provided timestamps, but others might not. If the receiving system cannot provide a GPS-locked timestamp, this field should not be included by the receiver station - instead, it should be inserted by the first server system with an NTP-synchronized clock. Most end users will not have NTP running, so AIS receiving software should generally not include a timestamp in a message, unless the transmitted AIS message really has one.

AIS Packet type 5: ship & voyage static data

If you don't have data for a certain field, do not include that key at all.

• imo
  • Integer. The IMO number of the ship.
• callsign
  • String. The callsign of the ship.
• shipname
  • String. The name of the ship.
• shiptype
  • Integer. The type ID of the ship.
• length
  • Integer. The length of the ship in meters.
• width
  • Integer. The width of the ship in meters.
• draught
  • Integer. The draught of the ship in meters.
• destination
  • String. The destination of the voyage.
• eta
  • Estimated time of arrival (ETA), "MM/DD/YYYY HH:MM:SS" string.

AIS Packet types 1-3: ship position

• lat
  • Float. The latitude for the current position of the ship.
• lon
  • Float. The longitude for the current position.
• speed
  • Float. The speed of the ship, in knots.
• course
  • Integer. The course of the ship, in degrees, 0-359. -1 == not available.
• heading
  • Integer. The heading of the ship, in degrees, 0-359. -1 == not available.
• status
  • Integer. The AIS status code of the ship.

Packet group message fields

• path
  • The path this message has traveled. When a message is forwarded, the system transmitting the message prepends it's information (name and optional URL) in the path. Each path component is an associative array containing two keys:
    • name - the name of the receiving site or database service
    • url - an URL for the receiving site
• msgs
  • An array of AIS packet messages which have traveled the same path.

Example messages

These examples have been formatted with extra whitespace for readability. JSON doesn't care about whitespace in the elements, so while these are valid JSON AIS messages, they should be transmitted in a more compact format (no line feeds and spaces between the elements).

AIS packet messages

An AIS position report for a single ship:

{
    "msgtype": 3,
    "mmsi":2320787,
    "status":14,
    "speed":0,
    "lon":-1.11023795604706,
    "lat":50.7996215820313,
    "course":0,
    "heading":0,
    "timestamp":"10/13/2008 09:14:01"
}

An AIS ship/voyage information report:

{
    "msgtype": 5,
    "mmsi":211189000,
    "imo":8705383,
    "callsign":"DQEJ",
    "shipname":"SASSNITZ",
    "shiptype":69,
    "length":0,
    "width":0,
    "eta":"10/13/2008 10:00:00",
    "draught":58,
    "destination":"TRELLEBORG/SASSNITZ",
    "timestamp":"10/13/2008 09:17:17"
}

Packet group messages

A complete packet group message with path data and a couple of ship positions. These positions were received by the receiving station called "OH7LZB", who gave it to marinetraffic, who in turn forwarded the data to aprs.fi.

{
    "path": [
        { "name": "aprs.fi", "url": "http://aprs.fi/" },
        { "name": "marinetraffic", "url": "http://www.marinetraffic.com/" },
        { "name": "OH7LZB" }
    ],
    "msgs": [
        {
             "msgtype": 3, "mmsi":2320787, "status":14, "speed":0,
             "lon":-1.11023795604706, "lat":50.7996215820313,
             "course":0, "heading":0, "timestamp":"10/13/2008 09:14:01"
        },
        {
             "msgtype": 3, "mmsi":1850257, "status":14, "speed":4,
             "lon":-3.26425604706, "lat":50.264556,
             "course":30, "heading":32, "timestamp":"10/13/2008 09:14:03"
        },
        {
             "msgtype": 3, "mmsi":9124762, "status":14, "speed":10,
             "lon":2.12512412, "lat":52.153213,
             "course":321, "heading":319, "timestamp":"10/13/2008 09:14:05"
        },
        {
             "msgtype": 5, "mmsi":211189000, "imo":8705383, "callsign":"DQEJ",
             "shipname":"SASSNITZ", "shiptype":69, "length":0, "width":0,
             "eta":"10/13/2008 10:00:00", "draught":58,
             "destination":"TRELLEBORG/SASSNITZ", "timestamp":"10/13/2008 09:17:17"
        }
    ]
}

HTTP polling (GET)

This format is used for passing JSON AIS messages using a polling mechanism. A client receives AIS data from a server by doing HTTP GET requests from a specific URL (for example, http://ais-server.example.com/jsonais/getdata). The server can require authentication (for example, using HTTP BASIC authentication, or by using a secret URL component).

The client can request data updated within a specific time range by using the firsttime and lasttime parameters. Time is specified in the common unix timestamp format (seconds since 1 Jan 1970 00:00:00 UTC). The matching logic is firsttime <= updatetime < lasttime. With a polling interval of 60 seconds, at t=1223887827 the client would ask for firsttime=1223887767&lasttime=1223887827, and at t=1223887887 it would ask for firsttime=1223887827&lasttime=1223887887). This way the client will only receive each updated point once, and the server can optimize it's backend database queries too.

(todo: consider using YYYYMMDDHHMMSS instead of unix timestamps, if people have trouble with parsing it...)

The client can also require excluding data which has passed through a specified JSON AIS server. This is done using the URL parameter excludepath. For example, excludepath=aprs.fi would filter out all entries which have "name"="aprs.fi" in the path.

The JSON AIS messages are returned by the server in container JSON message which specifies the protocol name (jsonais). This container is used so that we can extend the protocol later by adding fields here.

The content-type given by the server should be application/json, which is the content-type specified by the JSON RFC.

Example:

{
    "protocol": "jsonais",
    "messages": [
        { "msgtype": 5, .... },
        { "msgtype": 3, .... },
        { "msgtype": 3, .... },
    ]
}

HTTP push (POST)

This format is used for passing JSON AIS messages using a pushing mechanism. A client transmits AIS data to a server by doing HTTP POST requests to a specific URL (for example, http://ais-server.example.com/jsonais/postdata).

The array of AIS messages are formatted in the same way as with the HTTP GET method, and then encoded in a variable named jsonais of a HTTP POST request. Standard HTTP POST encoding methods are used - they can handle binary data, so JSON should go in just fine.

JSON AIS stream over TCP

This protocol is used for passing JSON AIS messages over a TCP stream. This has the least network overhead, since the connection is open all the time. It also provides the least latency, since the messages can be transmitted at any time, without a need for a polling timer.

(todo)