Integrate AIS Data

Please note that AIS integration is in active development and subject to change.

In most instances, when a container is loaded onto a vessel and the vessel embarks, visibility drops until the vessel arrives at its destination port and the container is discharged. However, on longer journeys, this invariably means increased uncertainty about delays and congestion.

Thanks to GateHouse Maritime’s extensive AIS data streams, we enable customers to not merely track containers, but to receive real-time AIS data from the vessel currently transporting a specific container. While our ETA 2.0 integration provides concise, and continuously updated, estimated time of arrival(s) and departure(s) throughout the entire journey of a container, integrating AIS data can provide even greater visibility on a vessel specific level.

The following steps are necessary to obtain AIS data of a given ship:

Note that Basic Authentication in the form of a username and password is necessary to submit a successful request. If you do not have any authentication details, please contact us.

If only an IMO number is known, a MMSI number must first be obtained. To do this, send a Post request to

https://demo2.ghmaritime.com/api/portserver/ship/info

containing the following Body and Content-Type: application/json:

{
   "ship": {
      "imo": 9454400
   }
}

Which, in case of IMO 9454400, returns the following:

{
    "ship": {
        "a2": "MT",
	"callsign": "9HA4987",
	"country": "Malta",
	"destination": "SUEZ CANAL",
	"draught": 14.5,
	"eta": "2021-04-17T21:00:00Z",
	"imo": 9454400,
	"mmsi": 215154000,
	"name": "CMA CGM CORTE REAL"
    }
}

In this case, we are only interested in the MMSI number 215154000. We use this to send a POST request to

https://demo2.ghmaritime.com/api/portserver/ship/historical/track

containing the following Body and Content-Type: application/json:

{
   "ship": {
      "mmsi": 215154000
   },
   "begin": "2021-04-01T00:00:00Z",
   "end": "2021-04-09T00:00:00Z",
   "resolution": "00:10:00"
}

By default, the past 240 hours of AIS data is accessible. The resolution, i.e. granularity, may be adjusted however relevant. We recommend using ten minutes or more. In this case, we grab the track data recorded between 01-APR-2021 (the begin field) and 09-APR-2021 (the end field). The response from the above request is a unique, one-time-use id granting you access to the requested track.

{
    "id": 8457
}

This id is then used to submit a GET request to

https://demo2.ghmaritime.com/api/portserver/ship/historical/track/<id>

A snippet of track 8457 is shown below:

{
    "distance": 3000667,
        "ship": {
	    "callsign": "9HA4987",
	    "imo": 9454400,
	    "mmsi": 215154000,
	    "name": "CMA CGM CORTE REAL"
	},
	"track": {
	    "coordinates": [
                [
                    104.15555166666667,
    		    1.2832483333333333,
		    "2021-04-01T00:00:17Z",
		    265.6,
		    9.2
	        ],
                ...
	        [
                    79.73488333333333,
		    6.666156666666667,
		    "2021-04-08T23:58:28Z",
		    347.3,
		    13.2
	        ]
            ],
	    "extensions": [
                "time",
		"cog",
		"sog"
            ],
            "type": "LineString"
    }
}

Each segment in the coordinates list, e.g.:

...
[
    79.73488333333333,
    6.666156666666667,
    "2021-04-08T23:58:28Z",
    347.3,
    13.2
]
...

contains, as noted in the extensions list, the following fields:

1. longitude (float) denoting the vessel’s longitude at time of event.
2. latitude (float) denoting the vessel’s latitude at time of event.
3. timestamp (datetime) of the specific track entry; all timestamps are in UTC.
4. cog (float) denoting the vessel’s course over ground at time of event.
5. sog (float) denoting the vessel’s speed over ground at time of event.

Please note how our output adheres to the GeoJSON-X (GeoJSON Extended) format as specified here: https://github.com/dret/GeoJSON-X. Importantly, the GeoJSON standard means that coordinates are listed as (longitude, latitude) and not (latitude, longitude).

A graphical representation of the track is shown in the screenshot above.