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
All coordinates are in WGS84. All timestamps are in seconds UTC unless otherwise specified.
API
1. Find ships in area GET http://ais.openshipdata.com/location/<version>/locations.json?<parameters>
Parameters
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 1 | |
| 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 VAARKAART_NL WATERKAART_NL TEST ANY AIS | ANY |
| API-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://ais.openshipdata.com/location/<version>/arrivals.json?<parameters>
Parameters
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 1 | |
| 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 |
| API-key | API secret key, to be requested from MarinePlan | string | – |
3. Lookup specific ships GET http://ais.openshipdata.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 |
| API-key | API secret key, to be requested from MarinePlan | string | – |
4. Upload single ship location POST http://ais.openshipdata.com/location/<version>/locations.json?<parameters>
Parameters
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 1 | |
| 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 | direction of travel in compass | 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 |
| API-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://ais.openshipdata.com/location/<version>/locations/<id>?<parameters>
Parameters
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 1 | |
| 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 | – |
| API-key | API secret key, to be requested from MarinePlan | string | – |
