> ## 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.
# Route Planner
> Returns the optimal sea route between ports, including total distance, ECA distance, estimated arrival time, travel duration, and route path points. Path points are provided every 300 nautical miles. Supports multi-leg routes by passing up to 5 ports. Costs 10 credits per request. Rate limit: 15 requests/min.
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
```json theme={null}
{
"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
```
## OpenAPI
````yaml GET /route-planner
openapi: 3.1.0
info:
title: Data Docked Maritime API
description: >-
A comprehensive maritime data API providing real-time vessel tracking, port
operations, inspection data, and more. Access AIS data, vessel particulars,
management information, and historical tracking data.
version: 1.0.0
contact:
name: Data Docked Support
url: https://datadocked.com/contact
servers:
- url: https://datadocked.com/api/vessels_operations
description: Production server
security:
- apiKey: []
tags:
- name: Account
description: Account management endpoints
- name: Vessel Operations
description: Vessel data, location, and tracking endpoints
- name: Port Operations
description: Port calls and port data endpoints
paths:
/route-planner:
get:
tags:
- Vessel Operations
summary: Route Planner
description: >-
Returns the optimal sea route between ports, including total distance,
ECA distance, estimated arrival time, travel duration, and route path
points. Path points are provided every 300 nautical miles. Supports
multi-leg routes by passing up to 5 ports. Costs 10 credits per request.
Rate limit: 15 requests/min.
operationId: getRoutePlanner
parameters:
- name: ports
in: query
required: true
description: >-
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.
schema:
type: string
example: NLRTM,SGSIN
- name: vessel_speed
in: query
required: true
description: >-
Vessel speed in knots. Used to calculate travel duration and
estimated arrival.
schema:
type: integer
example: 14
- name: departure_time
in: query
required: true
description: Departure date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
schema:
type: string
format: date-time
example: '2025-06-15T08:00:00Z'
- name: exclude_gateways
in: query
required: false
description: >-
Comma-separated list of gateways/straits to avoid. Values: corinth,
drake, kiel, magellan, malacca, messina, northeast, northwest,
oresund, panama, suez.
schema:
type: string
example: suez,panama
- name: eca
in: query
required: false
description: Pass 'avoid' to route around ECA (Emission Control Areas) zones.
schema:
type: string
enum:
- avoid
example: avoid
responses:
'200':
description: Successful response with route information
content:
application/json:
schema:
$ref: '#/components/schemas/RoutePlannerResponse'
example:
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
'400':
description: Bad request - Invalid parameter value
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
RoutePlannerResponse:
type: object
properties:
routes:
type: array
description: >-
Ordered list of route legs. One entry per consecutive pair of ports
in the request (e.g. 3 ports produces 2 legs).
items:
type: object
properties:
fromPort:
type: string
description: UNLOCODE of the leg's origin port
toPort:
type: string
description: UNLOCODE of the leg's destination port
distance:
type: object
properties:
distance:
type: integer
description: Leg distance in nautical miles
unit:
type: string
description: Distance unit (always 'kn' for nautical miles)
distanceInEca:
type: object
properties:
distance:
type: integer
description: Leg distance within ECA zones in nautical miles
unit:
type: string
description: Distance unit (always 'kn' for nautical miles)
crossing:
type: array
items:
type: string
description: Straits/canals/passages crossed on this leg
estimatedArrival:
type: string
format: date-time
description: Estimated arrival datetime for this leg (ISO 8601, UTC)
duration:
type: object
properties:
years:
type: integer
description: Leg duration - years component
month:
type: integer
description: Leg duration - months component
days:
type: integer
description: Leg duration - days component
hours:
type: integer
description: Leg duration - hours component
pathPoints:
type: array
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: >-
Ordered [longitude, latitude] coordinate points forming this
leg's path
Error:
type: object
properties:
error:
type: string
description: Error type
message:
type: string
description: Error message
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Your personal API key found in your profile dashboard at
https://datadocked.com/dashboard/my_keys
````