---
title: "Port Distances"
method: GET
path: "/api/v1/ports/{port_id}/distances"
tags: ["grandline"]
---

# Port Distances

`GET /api/v1/ports/{port_id}/distances`

## Request

- Base URL: `https://grandline.luzomi.com`
- URL: `https://grandline.luzomi.com/api/v1/ports/{port_id}/distances`
- Auth: none declared

Every cached destination reachable from `port_id`, with the distance for
the chosen variant — paginated and sorted shortest-first.

"Show me everywhere a vessel can sail from Mundra and how far." For voyage
analytics, rate-card builders, and port authorities. One metered call per
request (not per row). The empirical via_* leak guard (known-issue #1)
applies; the U-004 Cape *estimate* does not — this bulk listing reports
measured distances only, so a via_cape with no cached value comes back
`distance_nm: null` with an `availability` reason.

## Path parameters

- `port_id` integer, required

## Query parameters

- `variant` string: primary/via_suez/via_panama/via_cape.
- `country_iso2` string, nullable: Optional — only destinations in this country.
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- PortDistancesResponse
  - `origin_port_id` integer, required
  - `origin_port_name` string, required
  - `variant` string, required
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `rows` PortDistanceRow[], required
    - `destination_port_id` integer, required
    - `destination_port_name` string, required
    - `country_iso2` string, required
    - `distance_nm` number, nullable, required
    - `availability` string, 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)