Datalastic 3.1.1 API Reference

Datalastic maritime database knowledge zone and maritime API FAQ & support.

 

Getting Started: Access the Maritime API Key

  1. Go to Pricing 
  2. Choose your Maritime API Plan
  3. Subscribe to Maritime Data
  4. Instantly receive an email with your API key that you apply in the query part labeled as {YOUR_API_KEY}

To connect to Datalastic API, use the {YOUR_API_KEY} parameter with any valid API endpoint URL and set it to your access key.

api-key={YOUR_API_KEY}

Example API request: https://api.datalastic.com/api/v0/stat?api-key={YOUR_API_KEY}

 

Live Ship Tracker API & ETA

Real-time ship tracking API has 3 Endpoints:

  1. Basic: /vessel? – very fast and has all the basic real-time tracking data
  2. Pro: /vessel_pro? – provides extended additional data apart from basic about Estimated Time of Arrival, Actual Time of Departure, current draft, standartized destination name but it is slowlier than the endpoint above
  3. Bulk: /vessel_bulk? – lets you call up to 100 vessels in a single string.

Lets see examples of each of them:

 

 

Response:

{
    "data": {
        "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
        "name": "MAERSK CHENNAI",
        "mmsi": "566093000",
        "imo": "9525338",
        "eni": null,
        "country_iso": "SG",
        "type": "Cargo - Hazard A (Major)",
        "type_specific": "Container Ship",
        "lat": 6.303473,
        "lon": 3.201678,
        "speed": 0,
        "course": 326,
        "navigational_status": "Under Way using engine"" 
        "heading": 226,
        "destination": "TANGER MED",
        "last_position_epoch": 1620484020,
        "last_position_UTC": "2021-05-08T14:27:00Z"
        "eta_epoch": 1620671246
        "eta_UTC": "2021-05-10T18:27:26Z"
    },
    "meta": {
        "duration": 0.00246942,
        "endpoint": "/api/v0/vessel",
        "success": true
    }
}

Response:

{
    "data": {
        "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
        "name": "MAERSK CHENNAI",
        "mmsi": "566093000",
        "imo": "9525338",
        "eni": null,
        "country_iso": "SG",
        "type": "Cargo - Hazard A (Major)",
        "type_specific": "Container Ship",
        "lat": 6.303473,
        "lon": 3.201678,
        "current_draught":13.1
        "speed": 0,
        "course": 326,
        "navigational_status": "Under Way using engine" 
        "heading": 226,
        "destination": "TGLFW>NGAPP",
        "dest_port": "LOME"
        "dest_port_unlocode": "TGLFW"
        "last_position_epoch": 1620484020,
        "last_position_UTC": "2021-05-08T14:27:00Z"
        "atd_epoch": 1621469820
        "atf_UTC":"2021-05-20T00:17:00Z"
        "eta_epoch": 1622980800
        "eta_UTC":"2021-06-06T12:00:00Z"
      },
}

Response:

{
    "data": {
        "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
        "name": "MAERSK CHENNAI",
        "mmsi": "566093000",
        "imo": "9525338",
        "eni": null,
        "country_iso": "SG",
        "type": "Cargo - Hazard A (Major)",
        "type_specific": "Container Ship",
        "lat": 6.303473,
        "lon": 3.201678,
        "current_draught":13.1
        "speed": 0,
        "course": 326,
        "navigational_status": "Under Way using engine" 
        "heading": 226,
        "destination": "TGLFW>NGAPP",
        "dest_port": "LOME"
        "dest_port_unlocode": "TGLFW"
        "last_position_epoch": 1620484020,
        "last_position_UTC": "2021-05-08T14:27:00Z"
        "atd_epoch": 1621469820
        "atf_UTC":"2021-05-20T00:17:00Z"
        "eta_epoch": 1622980800
        "eta_UTC":"2021-06-06T12:00:00Z"
      },
}

Vessels in Location Tracking API

Choose a static point on the map or define a ship and track the radius zone around that selected point.

Choose a port and set radius that you want to monitor all inbound and outbound vessels in the port.

 

Location Zone Monitoring API example

https://api.datalastic.com/api/v0/vessel_inradius?api-key={YOUR_API_KEY}&lat=29.15915&lon=-89.25454&radius=3

https://api.datalastic.com/api/v0/vessel_inradius?api-key={YOUR_API_KEY}&mmsi=566093000&radius=5

 

API Parameters:

  • radius – Radius in NM. Max 50 NM
  • lat, lon – Geo coordinates of center
  • uuid – The search will be performed in a radius around the Vessel with this UUID.
  • mmsi – The search will be performed in a radius around the Vessel with this MMSI.
  • imo  – The search will be performed in a radius around the Vessel with this IMO.
  • port_uuid – The search will be performed in a radius around the Port with this UUID.
  • port_unlocode – The search will be performed in a radius around the Port with this UNLOCODE.

 

Response:

{
"data": {
"point": {
"lat": 29.15915,
"lon": -89.25454,
"radius": 0.25
},
"total": 2,
"vessels": [
{
"uuid": "f70aef75-3d20-bbcd-89f8-1cf9be0e3eee",
"name": "CANDACE",
"mmsi": "366955460",
"imo": "9343027",
"eni": null,
"country_iso": "US",
"type": "Tug",
"type_specific": "Towing Vessel",
"lat": 29.15608,
"lon": -89.25658,
"speed": 3.4,
"course": 13,
"heading": 14,
"destination": "XX XXX\u003eUS^0ZTT",
"last_position_epoch": 1605634800,
"last_position_UTC": "2020-11-17T17:40:00Z",
"distance": 0.213113085875055
},
{
"uuid": "3ec47f01-5f82-d51b-38c7-61d660c6a309",
"name": "E W ELLEFSEN",
"mmsi": "367323150",
"imo": null,
"eni": null,
"country_iso": "US",
"type": "Dredger",
"type_specific": "Dredger",
"lat": 29.1557,
"lon": -89.25619,
"speed": 0.9,
"course": 279,
"heading": 188,
"destination": "HOUSTON",
"last_position_epoch": 1605632220,
"last_position_UTC": "2020-11-17T16:57:00Z",
"distance": 0.224482533896964
}
]
},
"meta": {
"duration": 0.022402006,
"endpoint": "/api/v0/vessel_inradius",
"success": true
}
}

Historical Vessel Data API

Important!

Please first activate the vessels you want to see the historical data for. 

Activate the historical data for your chosen vessels by calling the query as in the example: 

https://api.datalastic.com/api/v0/add_vessel?api-key={YOUR_API_KEY}&mmsi=209453000&imo=9525338

Add the MMSI, IMO or UUID numbers of the ships as in the example above. After adding the vessels feel free to call the historical maritime data: 

Historical Maritime Data API example

http://api.datalastic.com/api/v0/vessel_history?api-key={API_KEY}&imo=9797058&days=2

 

http://api.datalastic.com/api/v0/vessel_history?api-key={API_KEY}&mmsi=56609300

API Parameters:

  • radius – Radius in NM. Max 50 NM
  • lat, lon – Geo coordinates of center
  • uuid – The search will be performed in a radius around the Vessel with this UUID.
  • mmsi – The search will be performed in a radius around the Vessel with this MMSI.
  • imo  – The search will be performed in a radius around the Vessel with this IMO.
  • port_uuid – The search will be performed in a radius around the Port with this UUID.
  • port_unlocode – The search will be performed in a radius around the Port with this UNLOCODE.

 

Response:

{
"data": {
"uuid": "edd5cbcf-5844-a0ba-c22c-3f53ec5c8bae",
"name": "OFFSHORE GUARDIAN",
"mmsi": "339301230",
"imo": "9797058",
"eni": null,
"country_iso": "JM",
"type": "Other",
"type_specific": "Offshore Supply Ship",
"positions": [
{
"lat": -9.52099,
"lon": 143.418,
"speed": 7,
"course": 229,
"heading": 229,
"navigation_status": "Under way using engine",
"destination": "Thursday Island",
"last_position_epoch": 1615692346,
"last_position_UTC": "2021-03-14T03:25:46Z"
},
{
"lat": -9.50044,
"lon": 143.417,
"speed": 7.3,
"course": 53,
"heading": 53,
"navigation_status": "Under way using engine",
"destination": "Thursday Island",
"last_position_epoch": 1615670076,
"last_position_UTC": "2021-03-13T21:14:36Z"
},
...
]
},
"meta": {
"duration": 0.005833293,
"endpoint": "/api/v0/vessel_history",
"success": true
}
}

Static Ship Data Finder API

Get descriptive data about ships name, IMO, MMSI, vessels type, dead weight tonnage, carriage capacity, year build, vessels country and more.

 

Response:

{
    "data": {
        "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
        "name": "MAERSK CHENNAI",
        "name_ais": "MAERSK CHENNAI",
        "mmsi": "566093000",
        "imo": "9525338",
        "eni": null,
        "country_iso": "SG",
        "country_name": "Singapore",
        "callsign": "9V9409",
        "type": "Cargo - Hazard A (Major)",
        "type_specific": "Container Ship",
        "gross_tonnage": 50869,
        "deadweight": 61614,
        "teu": "4500",
        "liquid_gas": null,
        "length": 249.12,
        "breadth": 37.4,
        "year_built": "2011",
        "is_navaid": false,
        "home_port": null
    },
    "meta": {
        "duration": 0.011030186,
        "endpoint": "/api/v0/vessel_info",
        "success": true
    }
}

Ship Data Finder API

This endpoint allows you to see ships without specifying MMSI numbers. You can use it when, for example, you would like to withdraw ship data for all the Cargo type vessels in Spain. This query will show information with a list of all vessels by defined parameter criteria. 

https://api.datalastic.com/api/v0/vessel_info?api-key={YOUR_API_KEY}&uuid=b8625b67-7142-cfd1-7b85-595cebfe4191

https://api.datalastic.com/api/v0/vessel_info?api-key={YOUR_API_KEY}&mmsi=566093000

https://api.datalastic.com/api/v0/vessel_info?api-key={YOUR_API_KEY}&imo=9525338

 

API Parameters:

  • uuid – Vessel UUID
  • mmsi – Vessel MMSI
  • imo  – Vessel IMO

 

Response:

{
    "data": {
        "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
        "name": "MAERSK CHENNAI",
        "name_ais": "MAERSK CHENNAI",
        "mmsi": "566093000",
        "imo": "9525338",
        "eni": null,
        "country_iso": "SG",
        "country_name": "Singapore",
        "callsign": "9V9409",
        "type": "Cargo - Hazard A (Major)",
        "type_specific": "Container Ship",
        "gross_tonnage": 50869,
        "deadweight": 61614,
        "teu": "4500",
        "liquid_gas": null,
        "length": 249.12,
        "breadth": 37.4,
        "year_built": "2011",
        "is_navaid": false,
        "home_port": null
    },
    "meta": {
        "duration": 0.011030186,
        "endpoint": "/api/v0/vessel_info",
        "success": true
    }
}

Maritime Ports Finder API

Find maritime ports information, location, time zone, country even when you dont know the exact port name. Just use fuzzy parameter and maritime ports finder API endpoint will find you the port you are looking for.

 

Maritime Port Finder example

Response:

{
{
"data": [
{
"uuid": "303548f5-e0ba-2bbc-528b-56fc44d79a87",
"port_name": "MALAGA",
"country_iso": "ES",
"country_name": "Spain",
"unlocode": "ESAGP",
"port_type": "Port",
"lat": 36.70981,
"lon": -4.417605,
"area_lvl1": "West Mediterranean",
"area_lvl2": "Gibraltar"
},
{
"uuid": "f2068011-72b8-2db8-880e-94c3fa2e2f29",
"port_name": "MALAGA",
"country_iso": "US",
"country_name": "USA",
"unlocode": "USMGA",
"port_type": "Marina",
"lat": 26.56593,
"lon": -81.9409,
"area_lvl1": "Gulf of Mexico",
"area_lvl2": "Gulf of Mexico"
}
],
"meta": {
"duration": 0.060431033,
"endpoint": "/api/v0/port_find",
"success": true
}
}

Track Your API Requests Data Usage

Depending on the subscription plan that you choose to subscribe for there can be a monthly database request package limit (unless you choose Developer Pro+ plan which has unlimited database requests).

Here is what you shoud know about database requests consumption model in Datalastic:

  • 1 vessel or port data request  = -1 point from your total consumption package
  • we protect you against errrors so only successful requests are counted. If there is no data retrieved in your request it does not affect your requests package.
  • if you request historical or bulk endpoint where multiple data elements are retrieved each element is counted as 1 point to be deducted from your total allowance.

Example:

You subscribed for Experimenter plan with 80000 requests/month and decided to call a bulk real-time vessel tracking API endpoint. You are requesting 10 vessels at once, that will count as -10 points from your total package so after that you will have 79990 requests avaliable in your monthly requests package.

Check how many database requests you still have

https://api.datalastic.com/api/v0/stat?api-key={YOUR_API_KEY} 

Response:

{   
 "data": {
        "user_id""{YOUR_API_KEY}",
        "key_status""Valid",
        "requests_made"112,
        "requests_remaining"888
    },

    "meta": {
        "duration"0.004715806,
        "endpoint""/api/v0/stat",
        "success"true
    }
}

API Values Explained

 

Value Legend Example
name Vessel name MAERSK CHENNAI
mmsi Maritime Mobile Service Identity 9 digits number for a ship identification 566093000
eta_UTC Estimated time of arrival in UTC “2021-06-11T16:49:00Z”
eta_epoch Estimated time of arrival 1624127400
current_draught Current reported draft of the vessel 9.5
atd_UTC Actual time of departure “2021-06-11T16:49:00Z”
imo International Maritime Organization 7 digits number for a ship identification 9525338
eni European Number of Identification 234456177
country_iso Vessel country name SG
country_name Full country name Singapore
type Vessel Type Cargo – Hazard A (Major)
type_specific Vessel subtype Container Ship
lat Current vessel latitude 6.303473
lon Current vessel longitude 3.201678
speed Current vessel speed in knots 5
navigational_status Vessel activity status Under way using engine
course Current vessel course in degrees 326
heading Current vessel heading in degrees 226
destination Typically a port name of the next planned stop ROTTERDAM
callsign Vessels number for vessel identification 9V9409
gross_tonnage Gross Registered Tonnage, is a ship’s total internal volume expressed in “register tons”, each of which is equal to 100 cubic feet (2.83 m3) 50869
deadweight A measure of how much weight a ship can carry in tonnage 61614
teu Container ship capacity is measured in twenty-foot equivalent units 4500
liquid_gas Ship liquid gas capacity null
length Vessel length in meters 249.12
breadth Vessel breadth in meters 37.4
year_built Year the vessel was built 2011

Ship Types AIS codes

AIS Code type_specific
1-19 Reserved for Future Use
20 WIG
29 Search and Rescue Aircraft 
30 Fishing
31 Towing
32 Towing: length exceeds 200m or breadth exceeds 25m
33 Dredger
34 Dive Ops 
35 Military Ops
36 Sailing Vessel
37 Pleasure Craft
40 HSC
50 Pilot 
51 Search and Rescue Vessel
52 Tug
53 Port Tender
54 Anti-Pollution Vessel 
55 Law Enforcement 
56 Local Vessel
58 Medical Transport 
59 Noncombatant
60 Passenger: All Ships
61 Passenger: Hazardous category A
62 Passenger: Hazardous category B
63 Passenger: Hazardous category C
64 Passenger: Hazardous category D
65 Passenger: Reserved for Future Use
66 Passenger: Reserved for Future Use
67 Passenger: Reserved for Future Use
68 Passenger: Reserved for Future Use
70 Cargo: All Ships
71 Cargo: Hazardous category A
72 Cargo: Hazardous category B
73 Cargo: Hazardous category C
74 Cargo: Hazardous category D
80 Tanker: All Ships
81 Tanker: Hazardous category A
82 Tanker: Hazardous category B
83 Tanker: Hazardous category C
84 Tanker: Hazardous category D
90 Other: All Ships
91 Other: Hazardous category A
92 Other: Hazardous category B
93 Other: Hazardous category C
94 Other: Hazardous category D

Subscribe and get the Key