UN/LOCODE java library

Package to facilitate the use of the UN/LOCODE scheme. UN/LOCODE is a geographic coding scheme developed and maintained by United Nations Economic Commission for Europe (UNECE). UN/LOCODE assigns codes to locations. While ISO 3166-1 standardizes country codes, ISO 3166-2 standardizes subdivisions (e.g. states or provinces within countries), UN/LOCODE builds upon these standards and standardizes over 100,000 locations around the world.

See https://www.unece.org/cefact/locode/welcome.html for details.

Data (CSV) sourced from https://datahub.io/core/un-locode, licensed under ODC Public Domain Dedication and Licence (PDDL).

Overview

Below is a high level overview of the data available with an excerpt of a few locations:

Change	Country	Location	Name	NameWoDiacritics	Subdivision	Status	Function	Date	IATA	Coordinates	Remarks
	AQ	CON	Concordia	Concordia		RL	--3-----	0507		7506S 12323E
+	AU	ABO	Alberton	Alberton	QLD	RL	--3-----	1801		2742S 15315E
	BO	ASC	Ascensión	Ascension	S	AI	--34----	0407		1542S 06305W
	IS	ISA	Isafjørdur - høfn	Isafjordur - hofn		AC	1-------	9601	IFJ
	GB	BSH	Brighton	Brighton	ESX	AF	1--4----	9511
	US	NYC	New York	New York	NY	AI	12345---	0401		4042N 07400W

The library contains the CSV with Location details issued by UNECE (available in /unlocode/un-locode.csv).

• Change indicates whether any change was made or the entry is marked for deletion
• Country is the 3166-1 alpha2 country code for the location
• Location is the code for that location. Note that this code is not unique and needs to be associated with a country.
• Name is the latin name
• NameWoDiacritics is the latin name without diatrics
• Subdivision is the ISO 3166-2 subdivision code for the location
• Status indicates the approval status within UN/LOCODE (See Status.java).
• Function lists potential functions for the location (port | rail terminal, airport, etc.)
• Date is the year and month the entry went into the list
• IATA, the IATA code for the location if different from the location code
• Coordinates geographical coordinates (latitude/longitude)

The CSV is parsed at class initialization, and the locations are searchable by various means.

Usage

Get a location by code

System.out.println(Locations.getLocations("US", "NYC"));

displays

[Location(country=US, code=NYC, name=New York, nameWithoutDiatrics=New York, subdivision=NY, status=AI, functions=Functions(port=true, railTerminal=true, roadTerminal=true, airport=true, postalExchangeOffice=true, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[2004-01], iata=, coordinates=40°42′N 74°0′W, remarks=, change=NONE)]

Find location codes for name starting with

Locations.findLocationIdsFromNameStartingWith("New Y").forEach(System.out::println);

displays

JM NYM
US NYC
GB NWY
US T5X
US NYQ
US Z2E
AL KRC

Using streams

Locations.findLocationIdsFromNameStartingWith("New Y").stream()
  .map(Locations::getLocations)
  .flatMap(Collection::stream)
  .collect(Collectors.toList())
  .forEach(System.out::println);

displays

Location(country=JM, code=NYM, name=New Yarmouth, nameWithoutDiatrics=New Yarmouth, subdivision=13, status=RQ, functions=Functions(port=false, railTerminal=false, roadTerminal=true, airport=false, postalExchangeOffice=false, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[2012-07], iata=, coordinates=17°53′N 77°16′W, remarks=, change=NONE)
Location(country=US, code=NYC, name=New York, nameWithoutDiatrics=New York, subdivision=NY, status=AI, functions=Functions(port=true, railTerminal=true, roadTerminal=true, airport=true, postalExchangeOffice=true, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[2004-01], iata=, coordinates=40°42′N 74°0′W, remarks=, change=NONE)
Location(country=GB, code=NWY, name=New York, nameWithoutDiatrics=New York, subdivision=LIN, status=AF, functions=Functions(port=false, railTerminal=false, roadTerminal=true, airport=false, postalExchangeOffice=false, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[1997-04], iata=, coordinates=UNKNOWN, remarks=, change=NONE)
Location(country=US, code=T5X, name=New York, nameWithoutDiatrics=New York, subdivision=TX, status=RL, functions=Functions(port=false, railTerminal=false, roadTerminal=true, airport=false, postalExchangeOffice=false, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[2014-07], iata=, coordinates=32°10′N 95°40′W, remarks=, change=NONE)
Location(country=US, code=NYQ, name=New York Mills, nameWithoutDiatrics=New York Mills, subdivision=MN, status=RQ, functions=Functions(port=false, railTerminal=false, roadTerminal=true, airport=false, postalExchangeOffice=false, multimodalFunctions=false, fixedTransportFunctions=false, borderCrossing=false), date=Optional[1993-07], iata=, coordinates=UNKNOWN, remarks=, change=NONE)
Location(country=US, code=Z2E, name=New York Mills, nameWithoutDiatrics=New York Mills, subdivision=NY, status=RL, functions=Functions(port=false, railTerminal=false, roadTerminal=false, airport=false, postalExchangeOffice=false, multimodalFunctions=true, fixedTransportFunctions=false, borderCrossing=false), date=Optional[2009-01], iata=, coordinates=43°6′N 75°17′W, remarks=, change=NONE)

Combining

Print the name, country and coordinates of all the locations that are both airports and border crossings, but not in Finland:

Locations.getAllLocations().stream()
  .filter(e -> e.getFunctions().isAirport() && e.getFunctions().isBorderCrossing() && !e.getCountry().equals("FI"))
  .map(e -> String.format("%s, %s (%s)", e.getName(), e.getCountry(), e.getCoordinates()))
  .forEach(System.out::println);

displays

Venezia, IT (45°26′N 12°20′E)
Ohrid, MK (41°7′N 20°48′E)
Petrovec, MK (41°56′N 21°36′E)
Artigas, UY (UNKNOWN)
Skopje, MK (UNKNOWN)
Columbus, US (31°49′N 107°38′W)
Calexico, US (32°40′N 115°28′W)
Hricov, SK (UNKNOWN)
Porto Santo Island, PT (33°4′N 16°20′W)
Houlton, US (46°7′N 67°50′W)
Limestone, US (46°54′N 67°49′W)
Tulcea, RO (45°11′N 28°48′E)
Pembina, US (48°57′N 97°15′W)
Progreso, US (26°5′N 97°57′W)
Rivera, UY (UNKNOWN)

Contributing

We welcome Your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source Project managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to the terms below. Except for the rights granted in this Agreement to American Express and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please fill out the Agreement.

License

Any contributions made under this project will be governed by the Apache License 2.0.

Code of Conduct

This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.