UN/LOCODE Validation in Python — Ports & Trade Locations

1. What is a UN/LOCODE?

UN/LOCODE (United Nations Code for Trade and Transport Locations) is an international standard maintained by UNECE (United Nations Economic Commission for Europe). It assigns a unique five-character code to over 100,000 locations in more than 240 countries and territories.

The directory covers seaports, inland ports, airports, rail terminals, road terminals, postal exchange offices, multimodal facilities, border crossing points, and other locations relevant to international trade and transport. Each location receives a code regardless of its size — from the world's busiest container ports to small inland customs posts.

UN/LOCODEs appear throughout trade documentation: bills of lading, customs declarations, letters of credit, certificates of origin, dangerous goods manifests, and EDI messages such as EDIFACT and UN/CEFACT. Using the standardised code instead of free-text location names eliminates ambiguity — there is no confusion between "Warsaw", "Warszawa", and "Varsovie" when the code is simply PLWAW.

UNECE publishes updated directories twice a year, adding new locations and decommissioning codes that are no longer in active use. The registry is freely available but validation requires checking both format correctness and existence in the current directory.

2. LOCODE structure

A UN/LOCODE consists of exactly five characters, split into two parts:

The first two characters are the ISO 3166-1 alpha-2 country code (e.g. PL for Poland, DE for Germany, US for the United States). The remaining three characters identify the specific location within that country. The location part can contain both letters and digits (A-Z, 2-9), though most codes use only letters.

Each location in the UN/LOCODE directory is tagged with one or more function classifiers indicating the type of facility available at that location:

Here are some well-known UN/LOCODEs:

3. Why LOCODE validation matters

4. The right solution

The IsValid UN/LOCODE API provides two endpoints: a validate endpoint that checks a single LOCODE and returns its full metadata (name, subdivision, functions, IATA code, coordinates), and a list endpoint that returns all LOCODEs for a given country.

Full parameter reference and response schema: UN/LOCODE Validation API docs →

5. Python code example

Using the isvalid-sdk package or the requests library. Install with pip install isvalid-sdk or pip install requests.

Validate a single LOCODE:

# locode_validator.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── Validate a UN/LOCODE ────────────────────────────────────────────────────

result = iv.locode("PLWAW")

if not result["found"]:
    print("LOCODE not found in the UN directory")
else:
    print(f"Name: {result['name']}")               # → 'Warszawa'
    print(f"Country: {result['country']}")           # → 'PL'
    print(f"Functions: {result['functions']}")       # → ['rail', 'road', 'airport', 'postal']
    print(f"IATA: {result['iata']}")                 # → 'WAW'
    print(f"Coordinates: {result['coordinates']}")   # → '5215N 02100E'

List all LOCODEs for a country:

# locode_list.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── List LOCODEs for Poland ─────────────────────────────────────────────────

locations = iv.locode.list(country="PL")

print(f"Found {len(locations)} locations in Poland")

for loc in locations[:5]:
    funcs = ", ".join(loc["functions"])
    print(f"  {loc['locode']} — {loc['name']} ({funcs})")

# Validate LOCODEs in a booking request
def validate_booking_locations(booking: dict) -> dict:
    origin = booking["origin"]
    destination = booking["destination"]

    origin_result = validate_locode(origin)
    dest_result = validate_locode(destination)

    errors = []

    if not origin_result["found"]:
        errors.append(f"Unknown origin LOCODE: {origin}")
    if not dest_result["found"]:
        errors.append(f"Unknown destination LOCODE: {destination}")

    if errors:
        return {"valid": False, "errors": errors}

    return {
        "valid": True,
        "origin": {
            "locode": origin_result["locode"],
            "name": origin_result["name"],
            "country": origin_result["country"],
            "functions": origin_result["functions"],
        },
        "destination": {
            "locode": dest_result["locode"],
            "name": dest_result["name"],
            "country": dest_result["country"],
            "functions": dest_result["functions"],
        },
    }

6. cURL example

Validate a single UN/LOCODE:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/locode?value=PLWAW"

Validate a port LOCODE:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/locode?value=DEHAM"

List all LOCODEs for a country:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/locode/list?country=PL"

7. Understanding the response

Validate endpoint — known LOCODE:

{
  "valid": true,
  "found": true,
  "locode": "PLWAW",
  "country": "PL",
  "location": "WAW",
  "name": "Warszawa",
  "nameAscii": "Warszawa",
  "subdivision": "14",
  "functions": ["rail", "road", "airport", "postal"],
  "iata": "WAW",
  "coordinates": "5215N 02100E"
}

Validate endpoint — unknown LOCODE:

{
  "valid": true,
  "found": false,
  "locode": "PLXYZ",
  "country": "PL",
  "location": "XYZ"
}

List endpoint — response for a country:

[
  {
    "locode": "PLGDN",
    "country": "PL",
    "location": "GDN",
    "name": "Gdansk",
    "nameAscii": "Gdansk",
    "subdivision": "22",
    "functions": ["port", "rail", "road", "airport", "postal"],
    "iata": "GDN",
    "coordinates": "5423N 01840E"
  },
  {
    "locode": "PLWAW",
    "country": "PL",
    "location": "WAW",
    "name": "Warszawa",
    "nameAscii": "Warszawa",
    "subdivision": "14",
    "functions": ["rail", "road", "airport", "postal"],
    "iata": "WAW",
    "coordinates": "5215N 02100E"
  }
]

8. Edge cases

result = iv.locode("PLXYZ")
# result["valid"] is True   (format is correct)
# result["found"] is False  (not in the UN directory)