Project

unlocodes

0.0
The project is in a healthy, maintained state
unlocodesmetanorma/unlocodeHomepageDocumentationSource CodeBug TrackerWiki
Vendored, offline access to the UN/LOCODE (United Nations Code for Trade and Transport Locations) dataset published by UNECE/UNCEFACT. Provides a model-driven Ruby registry for looking up LOCODE entries by code, country, function, status, name, and other classifiers.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
193
Stars
1
Forks
0
Watchers
0
 Releases
Current version
0.1.3
Total releases
2
First release
2026-07-01
Latest release
2026-07-01
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
0
Merged Pull Requests
1
Pull Request Acceptance Rate
100%
 Development
Primary Language
Ruby
Licenses
BSD-2-Clause
Average date of last 50 commits
2026-07-01
Reverse Dependencies
0

 Dependencies

Runtime

json
~> 2.6
lutaml-model
~> 0.8
 Project Readme

unlocodes

unlocodes is a Ruby gem that exposes the UN/LOCODE dataset (United Nations Code for Trade and Transport Locations) as a queryable in-memory registry.

The dataset is sourced from the UNECE/UNCEFACT LOCODE vocabulary, version-tagged 2025-1: https://opensource.unicc.org/un/unece/uncefact/vocab-locode/-/tags/2025-1

The full 2025-1 dataset (115,928 LOCODEs across 249 countries) is bundled inside the gem as lib/unlocodes/data/locode.jsonld and loads lazily into a typed registry on first use.

Installation

Add to your Gemfile:

gem 'unlocodes'

Usage

require 'unlocodes'

Unlocodes.find('CNSHA')                          # => #<Unlocodes::Entry code="CNSHA" ...>
Unlocodes.find('NLRTM').functions.map(&:code)    # => ["B", "R", "T", "A", "P"]
Unlocodes.where(country: 'CN').count             # => 1670
Unlocodes.where(function: 'B').count             # => 17912  (sea ports)
Unlocodes.where(function: 'A').count             # => 9009   (airports)
Unlocodes.find('CNPDG').coordinates              # => #<Coordinates lat=31.2333 lon=121.5000>

Function codes

The vocabulary publishes functions as unlcdf:1..unlcdf:9. The gem maps them to the UN/LOCODE manual’s letters:

unlcdf: Letter Meaning

1

B

Port (sea)

2

R

Rail terminal

3

T

Road terminal

4

A

Airport

5

P

Postal exchange office

6

I

Inland water transport

7

F

Ferry port

8

V

Pipeline

9

O

Other / border crossing

Use the letters in where(function: …​):

Unlocodes.where(function: 'B').count             # sea ports
Unlocodes.where(function: %w[B A]).count         # entries that are both port and airport

Distances

shanghai = Unlocodes.find('CNPDG').coordinates
rotterdam = Unlocodes.find('NLRTM').coordinates
shanghai.distance_to(rotterdam)                 # => 8922.0 (km, great-circle)

Data refresh

To refresh the bundled dataset when a new UNCEFACT edition is released:

bundle exec rake unlocodes:fetch         # default tag: 2025-1
UNLOCODE_TAG=2025-2 rake unlocodes:fetch

If the upstream tag layout changes, point UNLOCODE_PATH at the full JSON-LD URL:

UNLOCODE_PATH=https://example.org/path/unlocode.jsonld rake unlocodes:fetch

License

BSD-2-Clause. See LICENSE.