---
title: "Ports Nearest"
method: GET
path: "/api/v1/ports/nearest"
tags: ["grandline"]
---

# Ports Nearest

`GET /api/v1/ports/nearest`

## Request

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

Returns the N nearest ports to a given coordinate, sorted by
great-circle distance ascending.

Useful as the first link in the MCP tool chain — resolve an arbitrary
AIS ping / dropped pin / customer-supplied coordinate into the nearest
cataloged ports, then feed any of them into /routes/find.

Distance ordering: the SQL uses simple degree-distance for selection
(PostGIS-independent and cheap to scan), and the result is then
re-sorted in Python by the accurate haversine distance — important
near the poles and across the antimeridian, where degree-distance
diverges from great-circle ordering.

## Query parameters

- `lat` number, required: Latitude in WGS84 degrees
- `lon` number, required: Longitude in WGS84 degrees
- `n` integer: Number of ports to return (1-20)

## Response `200`

Successful Response

- PortDistance[]
  - `port_id` integer, required
  - `port_name` string, required
  - `country_iso2` string, required
  - `distance_nm` number, required
  - `lat` number, required
  - `lon` 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)