Skip to main content
GET
/
route-planner
Route Planner
curl --request GET \
  --url https://datadocked.com/api/vessels_operations/route-planner \
  --header 'x-api-key: <api-key>'
{
  "distance": {
    "distance": 8432,
    "unit": "kn"
  },
  "distanceInEca": {
    "distance": 120,
    "unit": "kn"
  },
  "crossing": [
    "Suez Canal",
    "Strait of Malacca"
  ],
  "estimatedArrival": "2025-07-02T14:30:00Z",
  "duration": {
    "years": 0,
    "month": 0,
    "days": 14,
    "hours": 19
  },
  "pathPoints": [
    [
      32.305024,
      30.573949
    ],
    [
      32.307437,
      30.584149
    ]
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.datadocked.com/llms.txt

Use this file to discover all available pages before exploring further.

Returns the optimal sea route between two ports, including total distance, ECA distance, estimated arrival time, travel duration, and route path points.
Credits: 1 credit per request

​
Parameters

ParameterTypeRequiredDescription
departure_portstringYesUNLOCODE of the departure port
arrival_portstringYesUNLOCODE of the arrival port
vessel_speedintegerYesVessel speed in knots
departure_timestringYesDeparture date/time in ISO 8601 format
exclude_gatewaysstringNoComma-separated list of gateways to avoid
ecastringNoPass avoid to route around ECA zones

​
Departure Time Format

Must follow the exact format: YYYY-MM-DDTHH:MM:SSZ 
✓ 2025-06-15T08:00:00Z
✗ 2025-06-15         (missing time component)
✗ 15-06-2025T08:00Z  (wrong date order)

​
Exclude Gateways

Comma-separated list of waterways/straits the route should avoid. Values are case-insensitive.
ValueGateway
corinthCorinth Canal
drakeDrake Passage
kielKiel Canal
magellanStrait of Magellan
malaccaStrait of Malacca
messinaStrait of Messina
northeastNortheast Passage
northwestNorthwest Passage
oresundØresund Strait
panamaPanama Canal
suezSuez Canal
Example: exclude_gateways=suez,panama

​
ECA Parameter

Controls whether the route avoids Emission Control Areas.
ValueBehavior
avoidRoute is planned to bypass ECA zones
(omitted)ECA zones are not considered

​
Response Fields

FieldTypeDescription
distance.distanceintegerTotal route distance in nautical miles
distance.unitstringAlways "kn" (nautical miles)
distanceInEca.distanceintegerDistance within ECA zones
distanceInEca.unitstringAlways "kn"
crossingarrayList of straits/canals/passages the route crosses
estimatedArrivalstringCalculated arrival datetime (ISO 8601, UTC)
duration.yearsintegerTravel duration - years component
duration.monthintegerTravel duration - months component
duration.daysintegerTravel duration - days component
duration.hoursintegerTravel duration - hours component
pathPointsarrayOrdered list of [lat, lng] coordinates (every 300 nautical miles)
estimatedArrival and duration are calculated server-side from departure_time and vessel_speed. All times are UTC.

​
Example Request

GET /route-planner?departure_port=NLRTM&arrival_port=SGSIN&vessel_speed=14&departure_time=2025-06-15T08:00:00Z&exclude_gateways=suez&eca=avoid

Authorizations

​
x-api-key
string
header
required

Your personal API key found in your profile dashboard at https://datadocked.com/dashboard/my_keys

Query Parameters

​
departure_port
string
required

UNLOCODE of the departure port (e.g., NLRTM for Rotterdam).

​
arrival_port
string
required

UNLOCODE of the arrival port (e.g., SGSIN for Singapore).

​
vessel_speed
integer
required

Vessel speed in knots. Used to calculate travel duration and estimated arrival.

​
departure_time
string<date-time>
required

Departure date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

​
exclude_gateways
string

Comma-separated list of gateways/straits to avoid. Values: corinth, drake, kiel, magellan, malacca, messina, northeast, northwest, oresund, panama, suez.

​
eca
enum<string>

Pass 'avoid' to route around ECA (Emission Control Areas) zones.

Available options:
avoid

Response

Successful response with route information

​
distance
object
​
distanceInEca
object
​
crossing
string[]

List of straits/canals/passages the route crosses

​
estimatedArrival
string<date-time>

Calculated arrival datetime in ISO 8601 format (UTC)

​
duration
object
​
pathPoints
number[][]

Ordered list of [latitude, longitude] coordinate points forming the route path (every 300 nautical miles)

Required array length: 2 elements