Hi everyone,
As you saw if you follow our
Geocoding API change log, yesterday we began adding
ISO 3166-2 codes to the components portion of each result. (If such a code or codes exists for the location, and if the underlying
data sources we rely on enable the determination of the correct codes(s).
ISO 3166-2 codes identify the subdivisions of a country, and adding them was a request we’ve had several times over the years. We hope adding these codes help developers cross link geocoding results with other datasets they may have.
Here’s an example from the response for an API request for coordinates 52.3877830, 9.7334394 - OpenCage’s registered office. You can see the components now include a list with one item DE-NI which corresponds to the German Bundesland (state) of Niedersachsen.
An immediate question is why we return a list rather than just the value. Well, as always in geospatial there are a few edge cases that developers might not anticipate:
First of all, a location can have more than one ISO 3166-2 code. Some countries (examples include the UK, France and Spain) have multiple levels of ISO 3166-2 codes. Here’s an example for coordinates 41.38455,2.16578 in Barcelona (and site of the upcoming Geomob Barcelona on 21st of June). As you can see, we return two ISO 3166-2 codes: ES-CT for the autonomous community of Catalonia, and ES-B for the province of Barcelona.
Secondly, many countries, particularly smaller countries, don’t have ISO 3166-2 codes at all. Here’s an example response from a request for the coordinates 41.90222,12.45724 (the location of the Vatican Obelisk at the center of St. Peter’s Square in the Vatican. Likewise areas like the oceans that do not belong to any country, will not have an ISO 3166-2 code.
Many countries use abbreviations for their codes, but many also use numeric codes. Or both. Here’s an example response from a request for the coordinates 48.85647,2.34081 - Pont Neuf in the center of Paris, France.
Finally, be aware that there are many dependent territories that for historical reasons have their own ISO 3166-1 code, but have a different country prefix in their ISO 3166-2 code. A good example is Puerto Rico. You can see the ISO 3166-1 alpha2 code is PR, but the ISO 3166-2 code is US-PR because Puerto Rico is part of the United States.
As always please send us your feedback, about this new feature or any others you might like us to add.
Happy geocoding, and warm greetings from OpenCage HQ in DE-NI,