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
- track an individual ship (free)
- track multiple ships (free)
All coordinates are in WGS84. All timestamps are in seconds UTC time, unless otherwise specified.
API
All methods use http(s)://ais.marineplan.com as the base path.
1. Find ships in area
GET /location/<version>/locations.json?<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 | ANY |
| key | API secret key, to be requested from MarinePlan | UUID | – |
2. Get planned arrivals in area
GET /location/<version>/arrivals.json?<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 | UUID | – |
3a. Lookup specific ships
This method call allows you to fetch multiple ships in one go.
GET /location/<version>/ships.json?<parameters>
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 2 | |
| 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 | UUID | – |
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 /location/<version>/ship.json?<parameters>
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 2 | |
| ship | the ships to be collected data for | ship name or MMSI number (spaces can be removed and matching is case insensitive) | – |
| 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 | UUID | – |
4. Upload single ship location
POST /location/<version>/locations.json?<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 | UUID | – |
| keys | series of keys, corresponding to the values | comma separated strings of JSON field names | – |
| values | series of values, corresponding to the keys | comma separated strings | – |
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 /location/<version>/locations/<id>?<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 | UUID | – |
6. Search for ships in area
GET /location/<version>/search.json?<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 | ANY |
| key | API secret key, to be requested from MarinePlan | UUID | – |
7. Track an individual ship
GET /location/<version>/ship.html?<parameters>
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 2 | – |
| language | output language | EN NL FR DE DA SV IT ES PT FY | EN |
| ship | name or MMSI | string | – |
8. Track Multiple ships
GET /location/<version>/ships.html?<parameters>
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 2 | – |
| language | output language | EN NL FR DE DA SV IT ES PT FY | EN |
| ships | names or MMSIs | comma separated strings | – |