# Seaports API
> The NGA World Port Index (WPI / Pub 150) as an API — 3,800+ maritime ports across 195 countries. Look up any port by its WPI number (e.g. 31140 → Rotterdam) or UN/LOCODE (e.g. NLRTM); search by name, country, harbor size or water body; or find every port within a radius of any coordinate (great-circle distance). Each record carries the UN/LOCODE, country, coordinates, harbor size and type, channel/anchorage/pier depths, maximum vessel length and draft, plus facility flags (container, oil/LNG terminal, ro-ro, dry dock, …). Ideal for shipping, logistics, maritime and supply-chain tools.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/seaports-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 45,000 calls/Mo, 8 req/s
- **Pro** ($17/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($43/Mo) — 1,200,000 calls/Mo, 50 req/s

## Endpoints

### Seaports

#### `GET /v1/nearby` — Ports within a radius of a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `51.9`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `4.48`
- `radius_km` (query, optional, string) — Search radius in km (1-20000, default 200)
- `limit` (query, optional, string) — Max results (1-100, default 10)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/seaports-api/v1/nearby?lat=51.9&lon=4.48"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "total": 27,
        "center": {
            "lat": 51.9,
            "lon": 4.48
        },
        "results": [
            {
                "id": "31140",
                "name": "Rotterdam",
                "country": "Netherlands",
                "latitude": 51.9,
                "longitude": 4.48333,
                "un_locode": "NL RTM",
                "water_body": "North Sea; North Atlantic Ocean",
                "distance_km": 0.2,
                "harbor_size": "Large",
                "harbor_type": "River (Basins)"
            },
            {
                "id": "31130",
                "name": "Schiedam",
                "country": "Netherlands",
                "latitude": 51.9,
                "longitude": 4.4,
                "un_locode": "NL SCI",
                "water_body": "North Sea; North Atlantic Ocean",
                "distance_km": 5.5,
                "harbor_size": "Very Small",
                "harbor_type": "River (Basins)"
            },
            {
                "id": "31120",
                "name": "Vlaardingen",
                "country": "Netherlands",
                "latitude": 51.9,
                "longitude": 4.35,
                "un_locode": "NL VLA",
                "water_body": "North Sea; North Atlantic Ocean",
                "distance_km": 8.9,
                "harbor_size": "Very Small",
                "harbor_type": "River (Basins)"
            },
            {
      
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/port` — A single port by WPI number or UN/LOCODE

**Parameters:**
- `id` (query, optional, string) — World Port Index number, e.g. 31140 (Rotterdam) Example: `31140`
- `locode` (query, optional, string) — UN/LOCODE, e.g. NLRTM

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/seaports-api/v1/port?id=31140"
```

**Response:**
```json
{
    "data": {
        "id": "31140",
        "name": "Rotterdam",
        "region": "Netherlands",
        "country": "Netherlands",
        "shelter": "Fair",
        "alt_name": null,
        "latitude": 51.9,
        "longitude": 4.48333,
        "un_locode": "NL RTM",
        "facilities": {
            "roro": null,
            "medical": true,
            "wharves": true,
            "dry_dock": true,
            "container": null,
            "lng_terminal": null,
            "oil_terminal": null,
            "cranes_container": null
        },
        "harbor_use": null,
        "water_body": "North Sea; North Atlantic Ocean",
        "harbor_size": "Large",
        "harbor_type": "River (Basins)",
        "channel_depth_m": 11,
        "anchorage_depth_m": 11,
        "cargo_pier_depth_m": 6.4,
        "max_vessel_draft_m": null,
        "max_vessel_length_m": null,
        "pilotage_compulsory": true
    },
    "meta": {
        "timestamp": "2026-05-31T03:55:45.123Z",
        "request_id": "1cfeba99-f4fb-4df2-9340-3f7e847b8995"
    },
    "status": "ok",
    "message": "Port retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search by name with country / harbor-size / water-body filters

**Parameters:**
- `q` (query, optional, string) — Name search, e.g. rotterdam
- `country` (query, optional, string) — Country, e.g. Spain Example: `Spain`
- `harbor_size` (query, optional, string) — Very Small | Small | Medium | Large
- `water_body` (query, optional, string) — Water body substring, e.g. Mediterranean
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/seaports-api/v1/search?country=Spain&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "query": null,
        "total": 52,
        "offset": 0,
        "filters": {
            "country": "spain",
            "water_body": null,
            "harbor_size": null
        },
        "results": [
            {
                "id": "38420",
                "name": "Hornillo",
                "country": "Spain",
                "latitude": 37.4,
                "longitude": -1.55,
                "un_locode": null,
                "water_body": "Mediterranean Sea; North Atlantic Ocean",
                "harbor_size": "Very Small",
                "harbor_type": "Coastal (Natural)"
            },
            {
                "id": "37770",
                "name": "La Coruna",
                "country": "Spain",
                "latitude": 43.36667,
                "longitude": -8.4,
                "un_locode": "ES LCG",
                "water_body": "North Atlantic Ocean",
                "harbor_size": "Small",
                "harbor_type": "Coastal (Natural)"
            },
            {
                "id": "38440",
                "name": "Alicante",
                "country": "Spain",
                "latitude": 38.33333,
                "longitude": -0.48333,
                "un_locode": "ES ALC",
                "water_body": "Mediterranean Sea; North Atlantic Ocean",
                "harbor_size": "Medium",
                "harbor_type": "Coastal (Breakwater)"
            },
            {
  
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & harbor-size breakdown

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/seaports-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "id = World Port Index number. Depths/sizes in metres. Facility flags may be null when unsurveyed.",
        "total": 3804,
        "fields": [
            "id",
            "name",
            "alt_name",
            "un_locode",
            "country",
            "region",
            "water_body",
            "latitude",
            "longitude",
            "harbor_size",
            "harbor_type",
            "harbor_use",
            "shelter",
            "channel_depth_m",
            "anchorage_depth_m",
            "cargo_pier_depth_m",
            "max_vessel_length_m",
            "max_vessel_draft_m",
            "facilities",
            "pilotage_compulsory"
        ],
        "source": "NGA World Port Index (WPI / Pub 150)",
        "countries": 195,
        "with_locode": 3345,
        "harbor_sizes": [
            {
                "size": "Very Small",
                "count": 2114
            },
            {
                "size": "Small",
                "count": 1017
            },
            {
                "size": "Medium",
                "count": 370
            },
            {
                "size": "Large",
                "count": 174
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T03:55:45.262Z",
        "request_id": "d0f1caf8-4cbe-4401-9fa7-b44b25ca88cd"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/seaports-api
OpenAPI spec: https://www.oanor.com/api/seaports-api/openapi.json