Developer Reference

Seaports

4,400+ global seaports across 210 countries, keyed by UN/LOCODE, with coordinates and the shipping companies that serve each port. Look up by country, search by name, filter by carrier, or find ports near a coordinate.

Get API Key ← Overview Interactive API Reference

GET /api/ports?country=:code

List Seaports by Country

All seaports in a country, by 2-letter country code. Available on every plan.

Query Parameters

Parameter	Type	Description
`country` required	`string`	2-letter country code (e.g. US, CN, NL)

Response Fields

Field	Type	Description
`success`	`boolean`	Indicates whether the request succeeded
`country`	`string`	The country code echoed back
`total`	`integer`	Number of ports returned
`ports[].name`	`string`	Port name
`ports[].unlocode`	`string`	UN/LOCODE (5-char international port code)
`ports[].countryCode`	`string`	2-letter country code
`ports[].countryName`	`string`	Country name
`ports[].lat`	`number`	Latitude
`ports[].lng`	`number`	Longitude
`ports[].transshipment`	`boolean`	Whether the port is a transshipment hub
`ports[].companies`	`array`	Shipping companies serving this port

Code Examples

curl "https://freightapis.dev/api/ports?country=CN" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "country": "CN",
  "total": 279,
  "ports": [
    {
      "name": "Shanghai",
      "unlocode": "CNSHA",
      "countryCode": "CN",
      "countryName": "China",
      "lat": 31.4001,
      "lng": 121.4971,
      "transshipment": true,
      "companies": ["COSCO", "EVERGREEN", "MAERSK"]
    }
  ]
}

GET /api/ports/:unlocode

Get Port by UN/LOCODE

A single port by its 5-character UN/LOCODE (e.g. CNSHA, NLROT). Available on every plan.

Path Parameters

Parameter	Type	Description
`unlocode` required	`string`	5-char UN/LOCODE (e.g. CNSHA)

Code Examples

curl "https://freightapis.dev/api/ports/CNSHA" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "port": {
    "name": "Shanghai",
    "unlocode": "CNSHA",
    "countryCode": "CN",
    "countryName": "China",
    "lat": 31.4001,
    "lng": 121.4971,
    "transshipment": true,
    "companies": ["COSCO", "EVERGREEN", "MAERSK"]
  }
}

GET /api/ports/search?q=:query

Search Seaports

Full-text search across port names. Results are paginated. Available on every plan.

Query Parameters

Parameter	Type	Description
`q` required	`string`	Search query (min 2 characters)
`page` optional	`integer`	Page number (default: 1)

Code Examples

curl "https://freightapis.dev/api/ports/search?q=rotterdam" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "query": "rotterdam",
  "ports": [ ... ],
  "total": 1,
  "currentPage": 1,
  "totalPages": 1
}

GET /api/ports/by-company?company=:name

List Seaports by Shipping Company

All ports served by a given carrier (e.g. COSCO, CMA CGM). Paginated. Available on every plan.

Query Parameters

Parameter	Type	Description
`company` required	`string`	Shipping company name (e.g. COSCO)
`page` optional	`integer`	Page number (default: 1)

Code Examples

curl "https://freightapis.dev/api/ports/by-company?company=COSCO" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "company": "COSCO",
  "ports": [ ... ],
  "total": 175,
  "currentPage": 1,
  "totalPages": 7
}

GET /api/ports/nearby?lat=:lat&lng=:lng&radius=:radius

Nearby Seaports

Ports near a GPS coordinate, sorted by distance (Haversine miles). Default radius 100 miles, max 1000. Available on every plan.

Query Parameters

Parameter	Type	Description
`lat` required	`number`	Latitude (-90 to 90)
`lng` required	`number`	Longitude (-180 to 180)
`radius` optional	`integer`	Radius in miles (default 100, max 1000)
`page` optional	`integer`	Page number (default: 1)

Code Examples

curl "https://freightapis.dev/api/ports/nearby?lat=31.4&lng=121.5&radius=200" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "center": { "lat": 31.4, "lng": 121.5 },
  "radiusMiles": 200,
  "ports": [
    { "name": "Shanghai", "unlocode": "CNSHA", "distanceMiles": 0.17, ... }
  ],
  "total": 76,
  "currentPage": 1,
  "totalPages": 4
}

POST /api/ports/batch

Batch Port Lookup

Look up multiple ports by UN/LOCODE in one call. Maximum 20 per request (50 for Enterprise). Available on every plan.

Request Body

Field	Type	Description
`unlocodes` required	`array`	Array of UN/LOCODEs (max 20; 50 for Enterprise)

Code Examples

curl -X POST "https://freightapis.dev/api/ports/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unlocodes": ["CNSHA", "NLROT"]}'

{
  "success": true,
  "results": {
    "CNSHA": { "name": "Shanghai", ... },
    "NLROT": { "name": "Rotterdam", ... }
  },
  "summary": { "requested": 2, "found": 2 }
}