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

parameterdescriptionvaluesdefault value
versionAPI version1 
areaWGS84 rectangleSW latitude, longitude; NE latitude, longitude, e.g. 52.5,4.80180;52.61,4.92Amsterdam area
maxagemaximum data age in seconds0 reflects any age
1800
movingfilter for moving or still ships0=still ships
1=moving ships
 1
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 –

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
bearingdirection of travel in compass degrees (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
 
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