OpenShipData API

The Open Ship Data API offers versatile marine vessel features search that allows to interchange data from vessels such as location, speed and destination. The following endpoints are available:

1. find ships in an area, moving or still
2. get planned arrivals in an area
3. lookup specific ships
4. upload single ship location data
5. wipe user data
6. search ships using text search

All coordinates are in WGS84. All timestamps are in seconds UTC unless otherwise specified.

API

1. Find ships in area

GET http(s)://ais.marineplan.com/location/<version>/locations.json?<parameters>

Parameters

Responses

The responses for the GET methods 1, 2 and 3 contains:

{
     "reports": [{
         "timeSecUtc": 1582790271,
         "point": {
             "latitude": 52.37547,
             "longitude": 4.90628
         },
         "destination": {
             "latitude": 52.37547,
             "longitude": 4.90628
         },
         "destinationName": "Amsterdam",
         "etaSecUtc": 1582793222,
         "boatName": "Albert",
         "callSign": "PF6426",
         "mmsi": "244013483",
         "lengthMeters": 16.0,
         "widthMeters": 3.0,
         "heightMeters": 0.0,
         "captain": "",
         "speedKmh": 8.89,
         "bearingDeg": 306.5,
         "vesselType": "YACHT",
         "source": "AIS",
         "boundingBox": {
             "topLeft": {
                 "latitude": 52.375515,
                 "longitude": 4.906206
             },
             "bottomRight": {
                 "latitude": 52.375425,
                 "longitude": 4.906354
             }
         }
     }, {
         "timeSecUtc": 1582790284,
         "point": {
             "latitude": 52.3764,
             "longitude": 4.89744
         },
         "destinationName": "",
         "etaSecUtc": 0,
         "boatName": "Pax",
         "callSign": "PG5061",
         "mmsi": "244780654",
         "lengthMeters": 18.0,
         "widthMeters": 4.0,
         "heightMeters": 0.0,
         "captain": "",
         "speedKmh": 0.56,
         "bearingDeg": 360.0,
         "vesselType": "YACHT",
         "source": "AIS",
         "boundingBox": {
             "topLeft": {
                 "latitude": 52.376445,
                 "longitude": 4.897366
             },
             "bottomRight": {
                 "latitude": 52.376355,
                 "longitude": 4.897514
             }
         }
     }, {
         "timeSecUtc": 1582790298,
         "point": {
             "latitude": 52.37099,
             "longitude": 4.88808
         },
         "destinationName": "Amsterdam",
         "etaSecUtc": 0,
         "boatName": "Iris",
         "callSign": "PC9987",
         "mmsi": "244820333",
         "lengthMeters": 16.0,
         "widthMeters": 3.0,
         "heightMeters": 0.0,
         "captain": "",
         "speedKmh": 0.56,
         "bearingDeg": 191.9,
         "vesselType": "YACHT",
         "source": "AIS",
         "boundingBox": {
             "topLeft": {
                 "latitude": 52.371035,
                 "longitude": 4.888006
             },
             "bottomRight": {
                 "latitude": 52.370945,
                 "longitude": 4.888154
             }
         }
     }, {
         "timeSecUtc": 1582790215,
         "point": {
             "latitude": 52.37179,
             "longitude": 4.88177
         },
         "destinationName": "A'dam",
         "etaSecUtc": 0,
         "boatName": "Rebel",
         "callSign": "PB4903",
         "mmsi": "244615787",
         "lengthMeters": 6.0,
         "widthMeters": 2.0,
         "heightMeters": 0.0,
         "captain": "",
         "speedKmh": 6.85,
         "bearingDeg": 64.7,
         "vesselType": "CONSOLE_BOAT",
         "source": "AIS",
         "boundingBox": {
             "topLeft": {
                 "latitude": 52.371835,
                 "longitude": 4.881696
             },
             "bottomRight": {
                 "latitude": 52.371745,
                 "longitude": 4.881844
             }
         }
     }]
 }

2. Get planned arrivals in area

GET http(s)://ais.marineplan.com/location/<version>/arrivals.json?<parameters>

Parameters

3a. Lookup specific ships

This method call allows you to fetch multiple ships in one go.

GET http(s)://ais.marineplan.com/location/<version>/ships.json?<parameters>

Parameters

3b. Lookup one ship only

This method call allows you to fetch a single ship. If none, or multiple ships are found, a HTTP result 404 or 400 is respectively thrown.

GET http(s)://ais.marineplan.com/location/<version>/ship.json?<parameters>

Parameters

4. Upload single ship location

POST http(s)://ais.marineplan.com/location/<version>/locations.json?<parameters>

Parameters

Adding extra arbitrary data

This feature allows ships to post extra data such as battery capacity, engine temperature, battery state-of-charge etc. These values can be accessed by API call 3 ships.json or ship.json in the shape of properties.

Passing this data uses the key/value principle, like “voltage”=”12.4”, where voltage is the key and 12.4 is the value. Multiple key/value-pairs can be added. All keys should be concatenated, separated by commas, and the values likewise. As an example the engine temperature and battery voltage are used:

&keys=engineTemperature,batteryVoltage&values=81.5,12.4

Please note no units are added and no validation is done. Values are stored and passed to any interested party using the ships.json or ship.json method in the API.

Route compression
The path ahead is compressed using a simple algorithm. All samples are separated by semicolons. A sample is latitude,longitude,ETA-time,ISRS-ID (optional=0). The first sample is absolute, e.g. 52.49150,4.80182,1586528445,12626161. Any subsequent samples are relative, where the latitude and longitude values are the difference relative to the last value, multiplied by 100,000 and its delta time is relative to the last sample in seconds. So if next sample is 52.49250,480190 in 50 seconds, the 2nd sample is 100,8,50,0.
There is no minimal requirement of the number of sample points. A kilometer ahead would in practice suffice to indicate the direction of travel.

5. Wipe user data

DELETE http(s)://ais.marineplan.com/location/<version>/locations/<id>?<parameters>

Parameters

6. Search for ships in area

GET http(s)://ais.marineplan.com/location/<version>/search.json?<parameters>

Parameters

Response

The response is similar to the Online Search API result:

{
	"results": [{
		"location": {
			"type": "SHIP",
			"point": {
				"latitude": 51.43242,
				"longitude": 0.68718
			},
			"placement": "NEAR",
			"distanceMeters": 0,
			"maxSpeedKmh": 0.0,
			"depthMeters": 0.0,
			"heightMeters": 0.0,
			"rule": 0,
			"flags": 0,
			"description": "Wec Van Eyck (210072000)",
			"name": "Wec Van Eyck (210072000)"
		},
		"score": 0.667,
		"scorePercentage": 67
	}, {
		"location": {
			"type": "SHIP",
			"point": {
				"latitude": 57.69589,
				"longitude": 10.61349
			},
			"placement": "NEAR",
			"distanceMeters": 0,
			"maxSpeedKmh": 0.0,
			"depthMeters": 0.0,
			"heightMeters": 0.0,
			"rule": 0,
			"flags": 0,
			"description": "Zircone (210056000)",
			"name": "Zircone (210056000)"
		},
		"score": 0.667,
		"scorePercentage": 67
	}, {
		"location": {
			"type": "SHIP",
			"point": {
				"latitude": 53.18946,
				"longitude": 5.43154
			},
			"placement": "NEAR",
			"distanceMeters": 0,
			"maxSpeedKmh": 0.0,
			"depthMeters": 0.0,
			"heightMeters": 0.0,
			"rule": 0,
			"flags": 0,
			"description": "Santa Helena 1 (210075000)",
			"name": "Santa Helena 1 (210075000)"
		},
		"score": 0.667,
		"scorePercentage": 67
	}],
	"parameters": {
		"rectangle": {
			"topLeft": {
				"latitude": 85.0,
				"longitude": -180.0
			},
			"bottomRight": {
				"latitude": -85.0,
				"longitude": 180.0
			}
		},
		"point": {
			"latitude": 0.0,
			"longitude": 0.0
		},
		"radiusMeters": 9444444,
		"query": "2100",
		"maxResults": 3,
		"types": ["SHIP"],
		"fuzzyLevel": 0,
		"language": "EN"
	}
}

7. Track an individual ship

GET http(s)://ais.marineplan.com/location/<version>/ship.html?<parameters>

8. Track Multiple ships.

GET http(s)://ais.marineplan.com/location/<version>/ships.html?<parameters>