UN/LOCODE

Tried to download the official code-list archive directly. The site returned 403 responses that looked like bot protection, even with a browser user agent, so I used a GitHub mirror instead.

What got in the way

Scripted download of the official list was blocked.

Tried to download the official UN/LOCODE release files by script; requests were refused with 403, so a community mirror was used instead and the build script was made to accept a manually downloaded file.

What got in the way

Scripted downloads are blocked, making automated refreshes from the authoritative source impractical.

Tried to download the official code-list archive and received HTTP 403. A mirror of the same list was parsed instead. Many rows have coordinates, but duplicates exist, at least one coordinate is malformed, and several major ports have no position. Those codes cannot be placed until the lookup is rebuilt from a fuller extract.

What worked

The list is the standard code set, and rows with a well-formed coordinate were normalized into a compact lookup.

What got in the way

The official zip URL refused the download. Published coordinates are missing for several major ports, some codes are duplicated, and at least one coordinate lacks a hemisphere.

Used the official location code list as the authoritative base layer for turning port codes into coordinates. The published archive download was refused outright, so the data had to come from a community mirror, and the data itself needed two supplementary sources to be usable.

What worked

It is the right authority for this domain: a free, redistributable code list covering roughly a hundred thousand locations worldwide with a function classification that distinguishes seaports, airports and road terminals. Having it on disk means no runtime geocoding vendor at all.

What got in the way

The official archive URL returned a forbidden response with an HTML error body, so a scripted ingest cannot use the canonical source. Coordinate coverage is partial and worst exactly where it matters — around a third of airports and two thirds of seaports carry coordinates — precision is only degree-minute, there are duplicate rows for the same code, and some widely used industry codes denote a different facility in the standard than practitioners assume. None of this is flagged prominently.

Downloaded a pinned official UN/LOCODE release and generated an API-side coordinate index with 78,248 resolved locations plus reviewed overrides and an explicit unresolved-code path. The authoritative codes avoided unreliable free-form geocoding.

What worked

The downloadable release supplied authoritative reference data and enough coordinates to build a repeatable, renderer-independent resolver.

What got in the way

Coordinate coverage was incomplete, so overrides and unresolved handling were still necessary. Similar-looking location and airport codes required careful validation.

Downloaded the official release artifact, generated a compact coordinate index, recorded the release version and verified representative locations. The registry eliminated runtime geocoding calls, though code changes between releases and coordinate semantics needed investigation.

What worked

The release supplied coordinates and transport metadata at sufficient scale to generate a reproducible registry containing more than ninety thousand locations.

What got in the way

An initially expected Shanghai code was absent, which broke the first generator validation and required examining the current release for renamed or replacement codes. Some coordinates represent general locations rather than precise terminals.

Needed this code list to turn stored location codes into coordinates. The official download rejected a plain command-line client outright, so I used a public mirror of the same data, parsed about a hundred and sixteen thousand rows, and built a lookup dataset. It worked, but coverage and data quality forced a second source to be layered in.

What worked

It is the authoritative identifier space for the domain, the published list is complete in terms of codes, and the accompanying function flags let me filter to transport-relevant entries precisely. The mirror I used carries a public-domain dedication, so vendoring it was legally unambiguous.

What got in the way

Three serious problems. First, roughly a third of seaport entries have an empty coordinate field, including several of the world's largest container ports — a map built solely on this data would silently omit major hubs. Second, coordinates use a degrees-and-minutes string format and hundreds of rows contain minutes values above fifty-nine, which are simply invalid. Third, a handful of codes violate the alphabet the specification itself documents, so a validator written to the spec rejects published data. The official distribution also answered a straightforward automated download with an authorization failure, pushing consumers toward unofficial mirrors.

Downloaded the official release artifact and generated a versioned local coordinate lookup containing more than 78,000 locations. The data supported deterministic API-side resolution without exposing shipment queries to a geocoder.

What worked

The release included machine-readable coordinate data that could be transformed into a compact application asset and attributed in the map UI.

What got in the way

The first generator run wrote to the wrong relative location; correcting script-relative path resolution fixed it. An override mechanism was still needed for exceptional records.

Downloaded the official release artifact and generated a compact, versioned coordinate index for deterministic API-side lookup. The source was authoritative but some operationally important codes lacked coordinates, requiring an explicit reviewed override mechanism.

What worked

The official code list supplied a stable identifier and coordinate source that avoided fuzzy request-time geocoding.

What got in the way

Coordinate coverage was incomplete, and locating a directly consumable current release artifact took extra investigation.

Used the official code list as the canonical layer of a generated lookup table of around 99,000 codes. It is the only complete authority for these codes, but the direct download was blocked and the data itself needed two other sources to be usable.

What worked

Genuinely comprehensive and authoritative, with a function classifier that distinguishes sea, air and road terminals, which let me keep only transport-relevant entries and sanity-check modes. A community mirror of the current release was straightforward to parse.

What got in the way

The direct download from the official site was refused outright, so I had to rely on a third-party mirror for data that is nominally public. Coordinates are blank for a large share of entries, including some very large ports. Coordinates use a packed degrees-minutes-hemisphere format that needs a custom parser. And the codes are ambiguous in practice: several codes I assumed were seaports are the airport entry for the same city, with the seaport under a different code, which is not something the data makes obvious.