---
title: "Find Route"
method: POST
path: "/api/v1/routes/find"
tags: ["grandline"]
---

# Find Route

`POST /api/v1/routes/find`

## Request

- Base URL: `https://grandline.luzomi.com`
- URL: `https://grandline.luzomi.com/api/v1/routes/find`
- Auth: none declared

Returns the empirical sea distance between two ports along the AIS-derived shipping graph.
Supports four route variants: primary (shortest), via_suez, via_panama, via_cape.
Steaming days calculated at 15 and 18 knots.

## Query parameters

- `origin` union, required: Origin port ID (int) or port name (str)
  - string
  - integer
- `destination` union, required: Destination port ID (int) or port name (str)
  - string
  - integer
- `variant` string: Route variant: primary, via_suez, via_panama, via_cape

## Response `200`

Successful Response

- RouteResponse
  - `origin_port_id` integer, required
  - `origin_port_name` string, required
  - `destination_port_id` integer, required
  - `destination_port_name` string, required
  - `variant` string, required
  - `distance_nm` number, required
  - `canal_transits` CanelTransit[]
    - `name` string, required
    - `type` string, required
  - `steaming_days_at_speed` SteamingDayEstimate[], required
    - `speed_knots` integer, required
    - `days` number, required

## Other responses

- `400`: Validation error with extra context
- `404`: Resource not found
- `422`: Validation Error
- `429`: Rate-limit exceeded — see X-RateLimit-* headers

---

[API](https://skmtc.dev/luzomi/apis/grandline-api.md) · [All operations](https://skmtc.dev/luzomi/apis/grandline-api/llms.txt) · [OpenAPI document](https://skmtc.dev/luzomi/apis/grandline-api/revisions/4ce06aea012b?raw)