---
title: "Ports reference"
method: GET
path: "/api/v2/maritime/ports"
tags: ["Maritime"]
---

# Ports reference

`GET /api/v2/maritime/ports`

The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft, channel depth, and container / oil / LNG terminal facilities. Filter by country, harbor size, terminal type, name, or proximity to a point / GEM energy asset. This is reference data (no date window). Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.

When a proximity center is set (`near`, `near_gem_id`), each row carries `distance_km` and results sort nearest-first. Standard envelope: `{ success, data, pagination, applied_filters }`.

## Query parameters

- `search` string
- `country` string
- `min_harbor_size` 'very_small' | 'small' | 'medium' | 'large'
- `lng_terminal` boolean
- `oil_terminal` boolean
- `near` string
- `near_gem_id` string
- `radius_km` number
- `bbox` string
- `limit` integer
- `cursor` string

## Response `200`

A page of ports. Each row: port_id, name, alt_name, unlocode, country (ISO-3), country_name, region, water_body, lat, lon, harbor_size, harbor_type, harbor_use, max_vessel_draft_m, channel_depth_m, lng_terminal / oil_terminal / container booleans, and distance_km (only when a proximity center is set).

- object
  - `success` boolean
  - `data` object[]
    - `port_id` string
    - `name` string
    - `alt_name` string, nullable
    - `unlocode` string, nullable
    - `country` string, nullable
    - `country_name` string
    - `region` string
    - `water_body` string
    - `lat` number
    - `lon` number
    - `harbor_size` string
    - `harbor_type` string
    - `harbor_use` string
    - `max_vessel_draft_m` number
    - `channel_depth_m` number
    - `lng_terminal` boolean
    - `oil_terminal` boolean
    - `container` boolean
    - `distance_km` number
  - `pagination` object
    - `limit` integer
    - `cursor` unknown
    - `next_cursor` unknown
  - `applied_filters` object
    - `search` string
    - `country` string
    - `min_harbor_size` string
    - `ignored` object

## Other responses

- `401` — Missing/invalid API key
- `403` — Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.
- `500` — Server error

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/revisions/01aaa6255180/schema)