---
title: "Search ports by name, country, UN/LOCODE or bounding box"
method: GET
path: "/v1/ports"
---

# Search ports by name, country, UN/LOCODE or bounding box

`GET /v1/ports`

## Request

- Base URL: `https://api.aistrail.com`
- URL: `https://api.aistrail.com/v1/ports`
- Auth: HTTP bearer

Ports of the World Port Index and UN/LOCODE. q matches the name or an alternate name (case and accent insensitive): exact names first, then names starting with q, then the rest; larger harbors first within each group. Response: ports (Port objects), count, total, offset, next_offset (null on the last page) and meta (attribution and notice). Port lookups use no credits.

## Query parameters

- `q` string
- `country` string
- `locode` string
- `bbox` string
- `port_id` string
- `limit` integer
- `offset` integer
- `format` 'json' | 'csv' | 'xlsx'

## Response `200`

ok

- object
  - `ports` Port[]
    - `id` integer: Port id: the World Port Index number for WPI ports; ports listed only in UN/LOCODE have ids from 10,000,000
    - `name` string
    - `alternate_names` string[]
    - `country` string, nullable: ISO 3166-1 alpha-2 country code
    - `locode` string, nullable: UN/LOCODE, e.g. NLRTM
    - `lat` number
    - `lon` number
    - `harbor_size` 'Large' | 'Medium' | 'Small' | 'Very Small' | 'null', nullable
    - `harbor_type` string, nullable
    - `radius_km` number: Radius of the port area used for port call detection

## Other responses

- `400`: RFC 9457 problem details
- `401`: RFC 9457 problem details
- `402`: RFC 9457 problem details
- `429`: RFC 9457 problem details

## Changes

- **2026-10-19** `e829e4345208`: 2 info
  - added the new enum value `xlsx` to the `query` request parameter `format`
  - added the media type `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` for the response with the status `200`

[Operation history](https://skmtc.dev/aistrail/apis/ais-trail-api/changes/v1/ports/get.md)

---

[API](https://skmtc.dev/aistrail/apis/ais-trail-api.md) · [All operations](https://skmtc.dev/aistrail/apis/ais-trail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aistrail/apis/ais-trail-api/revisions/e829e4345208?raw)