The problem
You have a UN/LOCODE and want to lookup the information associated with it.
Overview
UN/LOCODE is a system of codes maintained by the United Nations to uniquely identify locations critical for logistics. The five character codes provide a simple way for all parties in the supply chain to unambiguously refer to locations.
Converting a UN/LOCODE like
DEBRV
into the corresponding information about that
code is a useful functionality.
You can use the
OpenCage geocoding API
to find the information associated with UN/LOCODEs.
Simply send an API request with the query
q=LOCODE:DEBRV
You can test our geocoding API manually on our demo page.
Background
The United Nations publishes a list of UN/LOCODES twice per year.
The most recent list contains over 115,000 codes, and there is a variety of
information associated with each code.
Please see the excellent
UN/LOCODE Wikipedia page
for a detailed description of the type of data available
For UN/LOCODEs we return the following information in the
annotations
portion of the geocoding API result.
"UN/LOCODE" : {
"code" : "DEBRV",
"date" : "9501",
"function" : {
"meaning" : [
"port",
"rail terminal",
"road terminal",
"airport"
],
"raw" : "1234----"
},
"lat" : 53.5505392,
"lng" : 8.5851945,
"name" : "Bremerhaven",
"name_wo_diacritics" : "Bremerhaven"
},
Caveats / Points to Note
There are a few points you should note when working with UN/LOCODEs via the OpenCage geocoding API.
- Please see the official API documentation section dealing with UN/LOCODEs.
- UN/LOCODEs data quality is variable. Even in the best case the codes are associated with only a single coordinate point. Precise geographic boundaries are not provided.
- Searching for specific UN/LOCODEs is available to all API users. We also provide information about the nearest relevant UN/LOCODE as an annotation for all geocoding results to paying customers who request it. So that potential customers can see before buying this is turned on for all users of the API for all locations in Luxembourg.
- Some codes do not have coordinates at all in the official data, and we can not determine a location for them, and thus we are unable to work with about 2% of codes.
- A few codes in the official data have obviously wrong coordinates like 0,0 and thus we discard them.
Code Example
Here's a small example of making a request to the
OpenCage geocoding API in Python to determine information about the code
We also have libraries for over 30 other programming languages. including Javascript, PHP, Ruby, Java, and many others.
DEBRV.
We also have libraries for over 30 other programming languages. including Javascript, PHP, Ruby, Java, and many others.
from opencage.geocoder import OpenCageGeocode
from pprint import pprint
api_key = 'YOUR-API-KEY'
geocoder = OpenCageGeocode(api_key)
locode = 'DEBRV'
results = geocoder.geocode('LOCODE:' + locode)
# only interesged in the first result
result = results[0]
if (result['annotations']['UN/LOCODE']):
pprint(result['annotations']['UN/LOCODE'])
# {
# 'code': 'DEBRV',
# 'date': '9501',
# 'function': {
# 'meaning': [
# 'port',
# 'rail terminal',
# 'road terminal',
# 'airport'
# ],
# 'raw': '1234----'
# },
# 'lat': 53.5505392,
# 'lng': 8.5851945,
# 'name': 'Bremerhaven',
# 'name_wo_diacritics': 'Bremerhaven'
# }
# Your API key needs to be enabled for reverse geocoding. Contact us if you require UN/LOCODE
results = geocoder.reverse_geocode(-32.0497, 115.7421)
result = results[0]
if (result['annotations']['UN/LOCODE']):
pprint(result['annotations']['UN/LOCODE'])
# {
# 'code': 'AUSFT',
# 'date': '1601',
# 'function': {
# 'meaning': [
# 'road terminal'
# ],
# 'raw': '--3-----'
# },
# 'lat': -32.03,
# 'lng': 115.77,
# 'name': 'East Fremantle',
# 'name_wo_diacritics': 'East Fremantle'
# }