Route Planner - Data Docked

GET

route-planner

Route Planner

curl --request GET \
  --url https://datadocked.com/api/vessels_operations/route-planner \
  --header 'x-api-key: <api-key>'

{
  "routes": [
    {
      "fromPort": "NOAKM",
      "toPort": "JPAIM",
      "distance": {
        "distance": 7026,
        "unit": "kn"
      },
      "distanceInEca": {
        "distance": 201,
        "unit": "kn"
      },
      "crossing": [
        "Northeast passage",
        "Bering strait"
      ],
      "estimatedArrival": "2026-10-03T09:00:00Z",
      "duration": {
        "years": 0,
        "month": 0,
        "days": 24,
        "hours": 9
      },
      "pathPoints": [
        [
          5.177812,
          59.25707
        ],
        [
          5.336839,
          59.260461
        ]
      ]
    },
    {
      "fromPort": "JPAIM",
      "toPort": "AEAJM",
      "distance": {
        "distance": 6023,
        "unit": "kn"
      },
      "distanceInEca": {
        "distance": 0,
        "unit": "kn"
      },
      "crossing": [
        "Malacca strait",
        "Hormuz strait"
      ],
      "estimatedArrival": "2026-09-29T21:00:00Z",
      "duration": {
        "years": 0,
        "month": 0,
        "days": 20,
        "hours": 21
      },
      "pathPoints": [
        [
          131.280291,
          34.500359
        ],
        [
          131.3537,
          34.479694
        ]
      ]
    }
  ]
}

Returns the optimal sea route between ports, including total distance, ECA distance, estimated arrival time, travel duration, and route path points. Supports multi-leg routes with up to 5 ports.

Credits: 10 credits per request

Parameters

Parameter	Type	Required	Description
`ports`	string	Yes	Comma-separated list of UNLOCODEs (2–5 ports)
`vessel_speed`	integer	Yes	Vessel speed in knots
`departure_time`	string	Yes	Departure date/time in ISO 8601 format
`exclude_gateways`	string	No	Comma-separated list of gateways to avoid
`eca`	string	No	Pass `avoid` to route around ECA zones

Ports Parameter

Pass between 2 and 5 UNLOCODEs separated by commas (no spaces). The first port is the departure, the last is the final destination, and any ports in between are treated as waypoints in the given order.

✓ ports=NLRTM,SGSIN                     (point-to-point)
✓ ports=NLRTM,ESBCN,SGSIN               (one waypoint)
✓ ports=NLRTM,ESBCN,EGSUZ,INMUN,SGSIN   (max 5 ports)
✗ ports=NLRTM                           (need at least 2)

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.

Value	Gateway
`corinth`	Corinth Canal
`drake`	Drake Passage
`kiel`	Kiel Canal
`magellan`	Strait of Magellan
`malacca`	Strait of Malacca
`messina`	Strait of Messina
`northeast`	Northeast Passage
`northwest`	Northwest Passage
`oresund`	Øresund Strait
`panama`	Panama Canal
`suez`	Suez Canal

Example: exclude_gateways=suez,panama

ECA Parameter

Controls whether the route avoids Emission Control Areas.

Value	Behavior
`avoid`	Route is planned to bypass ECA zones
(omitted)	ECA zones are not considered

Response Format

The response is a routes array. Each entry represents one leg of the journey between two consecutive ports from your ports parameter. A 2-port request returns 1 leg, a 3-port request returns 2 legs, and so on (up to 4 legs for 5 ports).

Per-leg fields

Field	Type	Description
`fromPort`	string	UNLOCODE of the leg’s origin port
`toPort`	string	UNLOCODE of the leg’s destination port
`distance.distance`	integer	Leg distance in nautical miles
`distance.unit`	string	Always `"kn"` (nautical miles)
`distanceInEca.distance`	integer	Leg distance within ECA zones
`distanceInEca.unit`	string	Always `"kn"`
`crossing`	array	Straits/canals/passages crossed on this leg
`estimatedArrival`	string	Estimated arrival datetime for this leg (ISO 8601, UTC)
`duration.years`	integer	Leg duration - years component
`duration.month`	integer	Leg duration - months component
`duration.days`	integer	Leg duration - days component
`duration.hours`	integer	Leg duration - hours component
`pathPoints`	array	Ordered list of `[longitude, latitude]` coordinates forming this leg’s path

estimatedArrival and duration are calculated server-side from departure_time and vessel_speed. All times are UTC.

Example Response

{
  "routes": [
    {
      "fromPort": "NOAKM",
      "toPort": "JPAIM",
      "distance": { "distance": 7026, "unit": "kn" },
      "distanceInEca": { "distance": 201, "unit": "kn" },
      "crossing": ["Northeast passage", "Bering strait"],
      "estimatedArrival": "2026-10-03T09:00:00Z",
      "duration": { "years": 0, "month": 0, "days": 24, "hours": 9 },
      "pathPoints": [
        [5.177812, 59.25707],
        [5.336839, 59.260461]
      ]
    },
    {
      "fromPort": "JPAIM",
      "toPort": "AEAJM",
      "distance": { "distance": 6023, "unit": "kn" },
      "distanceInEca": { "distance": 0, "unit": "kn" },
      "crossing": ["Malacca strait", "Hormuz strait"],
      "estimatedArrival": "2026-09-29T21:00:00Z",
      "duration": { "years": 0, "month": 0, "days": 20, "hours": 21 },
      "pathPoints": [
        [131.280291, 34.500359],
        [131.3537, 34.479694]
      ]
    }
  ]
}

Example Request

GET /route-planner?ports=NOAKM,JPAIM,AEAJM&vessel_speed=14&departure_time=2026-09-09T00:00:00Z

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

ports

string

required

Comma-separated list of UNLOCODEs (no spaces). Minimum 2, maximum 5 ports. The first port is the departure, the last is the final destination, and intermediate ports are waypoints in order.

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

routes

object[]

Ordered list of route legs. One entry per consecutive pair of ports in the request (e.g. 3 ports produces 2 legs).

Show child attributes

Port Calls By VesselRetrieve historical port call data for a specific vessel including arrival/departure times and port information. Costs 5 credits per request. Rate limit: 15 requests/min.

Route Planner

curl --request GET \
  --url https://datadocked.com/api/vessels_operations/route-planner \
  --header 'x-api-key: <api-key>'

{
  "routes": [
    {
      "fromPort": "NOAKM",
      "toPort": "JPAIM",
      "distance": {
        "distance": 7026,
        "unit": "kn"
      },
      "distanceInEca": {
        "distance": 201,
        "unit": "kn"
      },
      "crossing": [
        "Northeast passage",
        "Bering strait"
      ],
      "estimatedArrival": "2026-10-03T09:00:00Z",
      "duration": {
        "years": 0,
        "month": 0,
        "days": 24,
        "hours": 9
      },
      "pathPoints": [
        [
          5.177812,
          59.25707
        ],
        [
          5.336839,
          59.260461
        ]
      ]
    },
    {
      "fromPort": "JPAIM",
      "toPort": "AEAJM",
      "distance": {
        "distance": 6023,
        "unit": "kn"
      },
      "distanceInEca": {
        "distance": 0,
        "unit": "kn"
      },
      "crossing": [
        "Malacca strait",
        "Hormuz strait"
      ],
      "estimatedArrival": "2026-09-29T21:00:00Z",
      "duration": {
        "years": 0,
        "month": 0,
        "days": 20,
        "hours": 21
      },
      "pathPoints": [
        [
          131.280291,
          34.500359
        ],
        [
          131.3537,
          34.479694
        ]
      ]
    }
  ]
}

​Parameters

​Ports Parameter

​Departure Time Format

​Exclude Gateways

​ECA Parameter

​Response Format

​Per-leg fields

​Example Response

​Example Request

Authorizations

Query Parameters

Response

Parameters

Ports Parameter

Departure Time Format

Exclude Gateways

ECA Parameter

Response Format

Per-leg fields

Example Response

Example Request