Open Ship Data 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

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: 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
 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

parameterdescriptionvaluesdefault value
versionAPI version1 
areaWGS84 rectangleSW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92World
maxagemaximum data age in seconds0 reflects any age
1800
sourcedata source filterOne of the following values:
NAVKID
VAARKAART_NL
WATERKAART_NL
TEST
ANY
AIS
 ANY
API-keyAPI secret key, to be requested from MarinePlanstring –
3. Lookup specific ships
GET http://ais.openshipdata.com/location/<version>/ships.json?<parameters>

Parameters

parameterdescriptionvaluesdefault value
versionAPI version1 
shipsthe ships to be collected data forsemicolon-separated list of ship names or MMSI numbers (spaces can be removed and matching is case insensitive)empty
areaWGS84 rectangleSW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92World
sourcedata source filterOne of the following values:
NAVKID
VAARKAART_NL
WATERKAART_NL
TEST
ANY
AIS
 ANY
API-keyAPI secret key, to be requested from MarinePlanstring –
4. Upload single ship location

POST http://ais.openshipdata.com/location/<version>/locations.json?<parameters>

Parameters

parameterdescriptionvaluesdefault value
versionAPI version1 
idunique ID to identify the boat, suggested is a once-generated UUID per user per appstringmmsi, callsign or empty
sourcedata source (use TEST as a playground) One of the following values:
NAVKID
VAARKAART_NL
WATERKAART_NL
TEST
AIS
pointboat current location in WGS84latitude,longitude
pathcompressed route ahead of the boatSee below for details.Empty
widthbeam of ship in metersfloat
heightmaximum height of boat in metersfloat
lengthboat length in metersfloat
destinationdestination point in WGS84latitude,longitude
destinationname description of destinationstring
eta ETA time in seconds UTCint0
speedspeed in kmhfloat0
bearingcompass direction of traveldegrees (North = 0, East = 90, etc.)0
nameboat namestringEmpty
type ship typeinteger, one of:
6: canoe
5: open console boat
4: recreation cruiser
3: recreation yacht
2: cargo vessel
captainname of captainstringEmpty
callsignbaot call sign (if certified)stringEmpty
mmsiboat MMSI (if certified)stringEmpty
draughtboat depth in metersfloat 0
API-keyAPI secret key, to be requested from MarinePlanstring –

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

parameterdescriptionvaluesdefault value
versionAPI version1 
idunique 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-keyAPI secret key, to be requested from MarinePlanstring –
Bitnami