Open Ship Data API | MarinePlan

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:

find ships in an area, moving or still
get planned arrivals in an area
lookup specific ships
upload single ship location data
wipe user data
search ships using text search

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

API

1. Find specific ships in area

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

Parameters

parameter	description	values	default value
version	API version	2
area	WGS84 rectangle	SW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92	Amsterdam area
maxage	maximum data age in seconds	0 reflects any age	1800
moving	filter for moving or still ships	0=still ships 1=moving ships	1
source	data source filter	One of the following values: NAVKID: only NavKid app VAARKAART_NL: only Vaarkaart NL app WATERKAART_NL: only Waterkaart NL app TEST: playground APPS: any of the 3 apps ANY: aggregation of all possible sources AIS: only AIS source APPS: only NAVKID/ VAARKAART_NL/ WATERKAART_NL sources	ANY
key	API secret key, to be requested from MarinePlan	string	–

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

parameter	description	values	default value
version	API version	2
area	WGS84 rectangle	SW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92	World
maxage	maximum data age in seconds	0 reflects any age	1800
source	data source filter	One of the following values: NAVKID VAARKAART_NL WATERKAART_NL TEST ANY AIS	ANY
key	API secret key, to be requested from MarinePlan	string	–

3. Lookup specific ships

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

Parameters

parameter	description	values	default value
version	API version	1
ships	the ships to be collected data for	semicolon-separated list of ship names or MMSI numbers (spaces can be removed and matching is case insensitive)	empty
area	WGS84 rectangle	SW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92	World
source	data source filter	One of the following values: NAVKID VAARKAART_NL WATERKAART_NL TEST ANY AIS	ANY
key	API secret key, to be requested from MarinePlan	string	–

4. Upload single ship location

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

Parameters

parameter	description	values	default value
version	API version	2
id	unique ID to identify the boat, suggested is a once-generated UUID per user per app	string	mmsi, callsign or empty
source	data source (use TEST as a playground)	One of the following values: NAVKID VAARKAART_NL WATERKAART_NL TEST AIS
point	boat current location in WGS84	latitude,longitude	–
path	compressed route ahead of the boat	See below for details.	Empty
width	beam of ship in meters	float
height	maximum height of boat in meters	float	–
length	boat length in meters	float	–
destination	destination point in WGS84	latitude,longitude	–
destinationname	description of destination	string	–
eta	ETA time in seconds UTC	int	0
speed	speed in kmh	float	0
bearing	compass direction of travel	degrees (North = 0, East = 90, etc.)	0
name	boat name	string	Empty
type	ship type	integer, one of: 6: canoe 5: open console boat 4: recreation cruiser 3: recreation yacht 2: cargo vessel	–
captain	name of captain	string	Empty
callsign	baot call sign (if certified)	string	Empty
mmsi	boat MMSI (if certified)	string	Empty
draught	boat depth in meters	float	0
key	API secret key, to be requested from MarinePlan	string	–

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

parameter	description	values	default value
version	API version	2
id	unique ID to identify the boat, suggested is a once-generated UUID per user per app (when the ID is lost, the data will time out and be removed after 24h)	string	–
key	API secret key, to be requested from MarinePlan	string	–

6. Search for ships in area

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

Parameters

parameter	description	values	default value
version	API version	2
area	WGS84 rectangle	SW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92	Amsterdam area
query	name or MMSI	string or partial string, may end with , e.g. “jaco”	–
max	maximum number of results	0..100	30
source	data source filter	One of the following values: NAVKID: only NavKid app VAARKAART_NL: only Vaarkaart NL app WATERKAART_NL: only Waterkaart NL app TEST: playground APPS: any of the 3 apps ANY: aggregation of all possible sources AIS: only AIS source APPS: only NAVKID/ VAARKAART_NL/ WATERKAART_NL sources	ANY
key	API secret key, to be requested from MarinePlan	string	–

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"
	}
}