Hi everyone,
welcome to day four of Launch Week 2024!
Today we go live with a new field in the components portion of Geocoding API results: _normalized_city.
A reality we are confronted with daily is that humans have an almost endless number of ways to organize their administration. Different countries (and even regions within countries) subdivide into cities, towns, municipalities, townships, villages, districts, suburbs, neighbourhoods, boroughs, etc, etc, etc. In some parts of the world these administrative divisions have clear definitions, in others they have evolved organically over centuries of history. There is not always a clear logic as to why one place is a village and another a town or whatever.
As you would expect we do our best to return the reality of the local situation for each geocoding result. But this often leaves geocoding API users - particularly those trying to build international products - confused about whether a location is in a city or a town or a village or what.
To solve this issue we now attempt to set the key _normalized_city within the components section of the API result. We do this simply by looking through the various fields in descending order (checking for the existence of city, then town, then township, and so forth).
Developers who want the name of the settlement can now simply look for this new field and not need to worry if they are dealing with a town or a village or whatever.
Here’s an example of the components portion of the response for the coordinates 51.37817, 10.13119
"components": {
"ISO_3166-1_alpha-2": "DE",
"ISO_3166-1_alpha-3": "DEU",
"ISO_3166-2": [
"DE-TH"
],
"_category": "travel/tourism",
"_normalized_city": "Heilbad Heiligenstadt",
"_type": "castle",
"castle": "Mainzer Schloss",
"continent": "Europe",
"country": "Deutschland",
"country_code": "de",
"county": "Landkreis Eichsfeld",
"house_number": "8",
"political_union": "European Union",
"postcode": "37308",
"road": "Friedensplatz",
"state": "Thüringen",
"state_code": "TH",
"town": "Heilbad Heiligenstadt"
},
You can see the new field "_normalized_city": "Heilbad Heiligenstadt",
Like the other component fields that we set (_type and category), rather than those we simply take from the underlying geodata we have available, this new field begin with an underscore. All of these fields are documented in the
section of the geocoding API documentation devoted to components.
We should note that while we do our best to set _normalized_city, it is not always possible. For example when the result is in a location where there is no concept of human settlement like coordinates in the middle of the ocean or similar. As ever we do the best we can with the data we have available to us.
Happy geocoding,