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, country code, and the names of container terminals in the port. 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",
      "display_name": "Rotterdam, Netherlands",
      "country": "NL",
      "subdivision": "ZH",
      "functions": ["port", "rail_terminal", "road_terminal", "airport", "postal_exchange"],
      "coordinates": { "lat": 51.916667, "lon": 4.5 },
      "status": "AF",
      "modalities": {
        "port": { "wpi_numbers": [31140], "type": "river_port", … },
        "airport": { "name": "Rotterdam The Hague Airport", "icao": "EHRD", … }
      }
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

GET/api/unlocode/nearby

Find the entries nearest to a point, closest first, e.g. the port for a terminal, jetty or offshore unit that has no UN/LOCODE of its own.

Parameter	Type	Description
lat	number	Latitude in decimal degrees. Required.
lon	number	Longitude in decimal degrees. Required.
country	string	ISO 3166-1 alpha-2 code. Repeatable for OR filtering. Optional.
function	string	Repeatable query param (e.g. function=port). Optional.
max_distance_km	number	Leave out entries further away. Optional.
limit	number	Max results. Default 10, max 50.

Request

curl "https://unlocode.vercel.app/api/unlocode/nearby?lat=1.263&lon=103.831&function=port&limit=3"

Response

{
  "results": [
    {
      "code": "SGSCT",
      "name": "Singapore Container Terminal",
      "display_name": "Singapore Container Terminal, Singapore",
      "country": "SG",
      "functions": ["port"],
      "coordinates": { "lat": 1.26667, "lon": 103.833 },
      "distance_km": 0.5,
      …
    },
    …
  ],
  "limit": 3
}

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",
  "display_name": "New York, United States",
  "country": "US",
  "subdivision": "NY",
  "functions": ["port", "rail_terminal", "road_terminal", "airport", "postal_exchange"],
  "coordinates": { "lat": 40.7, "lon": -74.0 },
  "status": "AI",
  "modalities": {
    "port": {
      "wpi_numbers": [7640],
      "type": "river_port",
      "harbor": { "size": "large", "type": "river_natural", "shelter": "excellent" },
      "region": "United States E Coast",
      "first_port_of_entry": true,
      "repair_capability": "major",
      "depths": { "channel_meters": 12.5, "anchorage_meters": 12.5, "cargo_handling_meters": 12.5 },
      "facilities": { "drydock": true, "tugs": true, "pilotage_compulsory": true, … },
      "container_terminals": [
        {
          "name": "APM TERMINALS ELIZABETH",
          "operator": "APM TERMINALS ELIZABETH",
          "smdg_code": "APMT",
          "coordinates": { "lat": 40.66, "lon": -74.148889 },
          "website": "https://www.apmterminals.com/en/port-elizabeth",
          "address": "5080 McLester Street, Elizabeth, NJ 07207, USA"
        },
        …
      ]
    }
  }
}

Port facilities API

Terminals and other facilities in a port, each listed under the port's UN/LOCODE. Container terminals (type container_terminal) are identified by that UN/LOCODE and their SMDG terminal code, the pair used in EDI messages. Base URL: https://unlocode.vercel.app/api/facilities. UN/LOCODE entries also list their container terminals under modalities.port.container_terminals.

GET/api/facilities/search

Search facilities by name or operator (in part) or by SMDG or UN/LOCODE code (exactly), filtered by country, UN/LOCODE or type.

Parameter	Type	Description
q	string	Text search. Optional.
country	string	ISO 3166-1 alpha-2 code. Repeatable. Optional.
unlocode	string	Facilities listed under this UN/LOCODE, primary or alternative. Repeatable. Optional.
type	string	Facility type, e.g. container_terminal. Repeatable. Optional.
limit	number	Max results per page. Default 50, max 200.
offset	number	Pagination offset. Default 0.

Request

curl "https://unlocode.vercel.app/api/facilities/search?q=eurogate&country=DE"

Response

{
  "results": [
    {
      "unlocode": "DEBRV",
      "type": "container_terminal",
      "smdg_code": "EGB",
      "country": "DE",
      "name": "EUROGATE CONTAINER TERMINAL BREMERHAVEN",
      "operator": "EUROGATE CONTAINER TERMINAL BREMERHAVEN",
      "coordinates": { "lat": 53.586111, "lon": 8.529167 },
      "website": "https://www1.eurogate.de/en/terminals/#bremerhaven",
      "address": "Senator-Borttscheller-Str. 1, 27568 Bremerhaven, Germany"
    },
    …
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

GET/api/facilities/:unlocode/:code

Look up a facility by the UN/LOCODE it is listed under (primary or alternative) and its code: the SMDG code for a container terminal. Case-insensitive. Returns 204 when not found.

Parameter	Type	Description
unlocode	path	The UN/LOCODE, e.g. DEHAM.
code	path	The SMDG terminal code, e.g. EGH.

Request

curl "https://unlocode.vercel.app/api/facilities/CNNBO/BLCT1"

Response

{
  "unlocode": "CNNBO",
  "type": "container_terminal",
  "smdg_code": "BLCT1",
  "alternative_unlocode": "CNNBG",
  "country": "CN",
  "name": "NINGBO BEILUN INTERNATIONAL CONTAINER TERMINAL (NBCT)",
  "operator": "NINGBO BEILUN INTERNATIONAL CONTAINER TERMINAL CO., LTD.",
  "coordinates": { "lat": 29.936111, "lon": 121.866667 },
  "website": "https://www.nbct.com.cn/",
  "address": "No. 178, North Pole Star Road, Beilun District, Ningbo, Zhejiang Province, China",
  "notes": "Ningbo Beilun Phase 2"
}

GET/api/facilities/nearby

Find the facilities nearest to a point, closest first, with their distance.

Parameter	Type	Description
lat	number	Latitude in decimal degrees. Required.
lon	number	Longitude in decimal degrees. Required.
country	string	ISO 3166-1 alpha-2 code. Repeatable. Optional.
type	string	Facility type. Repeatable. Optional.
max_distance_km	number	Leave out facilities further away. Optional.
limit	number	Max results. Default 10, max 50.

Request

curl "https://unlocode.vercel.app/api/facilities/nearby?lat=53.53&lon=9.91&limit=3"

Response

{
  "results": [
    { "unlocode": "DEHAM", "type": "container_terminal", "smdg_code": "EGH", "name": "EUROGATE CONTAINER TERMINAL HAMBURG", …, "distance_km": 0.3 },
    …
  ],
  "limit": 3
}

GET/api/facilities/meta

Return metadata for the loaded facilities dataset: its version and when it was generated.

Request

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

Response

{
  "datasetVersion": "2026-06-09",
  "generatedAt": "2026-09-28T00:00:00.000Z"
}

Download the full datasets

Every UN/LOCODE entry and every port facility is also published as a static file, in the same shape as the lookup responses, with one small meta.json describing both: poll it to see when a dataset changes. The files are served from the CDN with an ETag: send it back in If-None-Match and you get 304 Not Modified until the dataset changes. Compressed, the UN/LOCODE download is a few megabytes.

# Version, generation time, count and path of each dataset (small, cheap to poll)
curl "https://unlocode.vercel.app/data/meta.json"

# UN/LOCODE entries: { "datasetVersion", "generatedAt", "entries": [...] }
curl --compressed -o unlocode.json "https://unlocode.vercel.app/data/unlocode.json"

# Port facilities: { "datasetVersion", "generatedAt", "facilities": [...] }
curl --compressed -o facilities.json "https://unlocode.vercel.app/data/facilities.json"

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, and the names (or exact codes) of container terminals in the port.
--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.
--display_name combines the location name with the English country name (e.g. Rotterdam, Netherlands) so it can be shown to people as-is.
--coordinates are decimal latitude/longitude values, or null when no source has them. They start from UN/LOCODE and are checked against administrative boundaries: points in the wrong place are corrected, and missing ones are filled from other open sources.
--modalities adds details for some functions: port (harbor, depths, maximum vessel size, terminals and facilities) and airport (name, ICAO code, type, elevation and runways). It is omitted when there are no details, and unknown values are left out rather than returned as false or 0.