Skip to main content

UN/LOCODE Lookup

A UN/LOCODE is the UNECE's code for a trade-and-transport location — US NYC for New York, NL RTM for Rotterdam. If you're moving freight, filing customs, or matching a shipping record to a place, you need these codes, and you usually have either a place nametoponymA proper name for a geographic place. or a coordinate to start from. The @mailwoman/un-locode-lookup package goes both ways, over the UNECE code list in a node:sqlite database.

Like the timezone lookup, it's server-side and you build the database once before the first query.

Build the database​

Grab the UNECE code list (code-list.csv) and build the read-only DB:

npx @mailwoman/un-locode-lookup build --csv code-list.csv --out un-locode.db

CLI usage​

By countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. and place nametoponymA proper name for a geographic place., or by nearest coordinate. The coordinate form needs a leading -- before the negative longitude, or the CLI's flag parser reads -74.0060 as an unknown option:

npx @mailwoman/un-locode-lookup --db un-locode.db --country NL --name "Rotterdam"
# {"unLocode":"NL RTM"}

npx @mailwoman/un-locode-lookup --db un-locode.db -- 40.7128 -74.0060
# {"unLocode":"US NYC"}

Programmatic usage​

import { UnLocodeLookup, makeUnLocodeAnnotator } from "@mailwoman/un-locode-lookup"

const lookup = new UnLocodeLookup({ databasePath: "un-locode.db" })

lookup.byName("US", "New York") // "US NYC"
lookup.nearest(51.92, 4.48) // "NL RTM"

byName is exact, but the match is diacriticdiacriticAn accent mark that modifies a letter (é, ñ, ç). Address normalization must fold diacritics for matching without discarding the information a user typed.-folded and case-insensitive, so "São Paulo" and "sao paulo" both land. nearest covers the roughly 80% of entries that carry coordinates (93k of 116k), which is most of what you'll reach for. Wrap it as an Annotator to fill AnnotationSet.unLocode on a resolved result:

const annotator = makeUnLocodeAnnotator(lookup)

Data​

The UNECE UN/LOCODE code list is public domain, so this one carries no share-alike obligation — see Data licensing for how the sources differ.