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.

Message fields

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

Mandatory fields in all messages:

• msgtype
  • Integer. This is the type of the AIS message. 5 for ship the ship information packet, 3 or 4 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 travelled. When a message is forwarded, the system transmitting the message prepends it's information (name and optional URL) in the 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).

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

{
    "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",
    "path": [
        { "name": "OH7LZB" }
    ]
}

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

(todo)

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)