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 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').

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".
• 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.

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.

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 JSON AIS message with path data and a couple of ship positions:

{
    "path": [
        { "name": "aprs.fi", "url": "http://aprs.fi/" },
        { "name": "marinetraffic", "url": "http://www.marinetraffic.com/" },
        { "name": "OH7LZB" }
    ],
    "data": [
        {
             "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)