unlocode/

unlocode/

Search, API, and React components for UN/LOCODE

An open-source toolkit for the United Nations Code for Trade and Transport Locations. Search the full dataset, 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

API

  • --2 endpoints: search and lookup by code
  • --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

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"