UN/LOCODE API Reference

Public REST API for searching and looking up UN/LOCODE entries. Endpoints support CORS.

Base URL: https://unlocode.vercel.app/api/unlocode. All responses include Access-Control-Allow-Origin: * so you can call these from any origin.

GET/api/unlocode/search

Search the UN/LOCODE database. Returns paginated results filtered by text query, country, and/or function.

Parameter	Type	Description
q	string	Text search across name, code, and country code. Optional.
country	string	ISO 3166-1 alpha-2 code. Repeatable for OR filtering (e.g. country=US&country=CA). Optional.
function	string	Repeatable query param (e.g. function=port&function=airport). Optional.
limit	number	Max results per page. Default 50, max 200.
offset	number	Pagination offset. Default 0.

Request

curl "https://unlocode.vercel.app/api/unlocode/search?q=rotterdam&country=NL&limit=5"

Response

{
  "results": [
    {
      "code": "NLRTM",
      "name": "Rotterdam",
      "country": "NL",
      "subdivision": "ZH",
      "functions": ["port", "rail_terminal", "road_terminal", "airport"],
      "coordinates": { "lat": 51.916667, "lon": 4.483333 },
      "status": "AI"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

GET/api/unlocode/meta

Return metadata for the loaded UN/LOCODE dataset.

Request

curl "https://unlocode.vercel.app/api/unlocode/meta"

Response

{
  "datasetVersion": "2024-2",
  "generatedAt": "2026-02-22T00:00:00.000Z"
}

GET/api/unlocode/:code

Look up a single entry by its UN/LOCODE. Case-insensitive. Returns 204 when the code is not found.

Parameter	Type	Description
code	path	The UN/LOCODE, e.g. USNYC, GBLON, SGSIN.

Request

curl "https://unlocode.vercel.app/api/unlocode/USNYC"

Response

{
  "code": "USNYC",
  "name": "New York",
  "country": "US",
  "subdivision": "NY",
  "functions": ["port", "rail_terminal", "road_terminal", "airport", "postal_exchange"],
  "coordinates": { "lat": 40.7, "lon": -74.0 },
  "status": "AI"
}

Notes

--Data is generated from official UNECE UN/LOCODE CSV releases and loaded from JSON for fast local lookup.
--Search is case-insensitive and matches against the location name, code, and country code.
--GET /:code returns 204 when no matching entry exists.
--Lookup responses are cached with a longer TTL than search responses.
--GET /meta reports the loaded dataset version and generation timestamp.
--coordinates are normalized to decimal latitude/longitude values, or null when not available in source data.