unlocode/

unlocode/

Search, API, and React components for UN/LOCODE

A toolkit for the United Nations Code for Trade and Transport Locations. Search the full dataset, with checked coordinates and port and airport details, call the REST API from any client, or drop the React component into your forms.

What is UN/LOCODE?

UN/LOCODE is a geographic coding scheme maintained by the United Nations Economic Commission for Europe (UNECE). It assigns a unique 5-character code to locations across 249 countries and territories that are significant for international trade and transport: ports, airports, rail terminals, road terminals, postal exchange offices, inland clearance depots, and border crossings.

The code format is CC LOC where CC is the ISO 3166-1 alpha-2 country code and LOC is a 3-character location identifier. For example, USNYC is New York and NLRTM is Rotterdam.

The official dataset is published at unece.org and is updated several times per year.

How this toolkit works

Data

  • --The official UNECE UN/LOCODE code list, refreshed monthly by automation
  • --Coordinates checked against administrative boundaries: wrong points corrected, missing ones filled from other sources
  • --Port details: harbor, depths, maximum vessel size, terminals and facilities
  • --Airport details: ICAO code, type, elevation and runways

API

  • --3 endpoints: search, lookup by code, and dataset metadata
  • --Paginated search with text, country, and function filters
  • --CORS headers on every response: call from any origin
  • --Cache-Control headers for CDN edge caching

Search UI

  • --Country combobox + function multi-select in a ButtonGroup, plus free text input
  • --SWR with keepPreviousData to avoid layout flicker during fetches
  • --300ms debounce on text input to limit API calls
  • --Detail panel shows full entry info for the selected result, with a port and airport summary

Form component

  • --Compact ButtonGroup with country picker and search popover
  • --Displays the selected UN/LOCODE inline after selection with a clear action
  • --Controlled value + onValueChange interface, works with any form library
  • --Same async search pattern as the search page

Quick start

# Search for ports in the Netherlands
curl "https://unlocode.vercel.app/api/unlocode/search?country=NL&function=port&limit=5"

# Look up a single code
curl "https://unlocode.vercel.app/api/unlocode/NLRTM"