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