Admin Hierarchy for each country (geocoding)

Question

I'm using the Geocoder REST API from HERE to fetch latitude/longitude points for a given freeform or structured address. However, I am not dealing with U.S. addresses, instead I will be using Mexican or Brazilian addresses.

In the Geocoder API, certain attributes mention an 'Admin Hierarchy' for determining when to use city, region, district, etc. Both of my countries do not follow the typical City/State hierarchy we use in the U.S.

I'm wondering: Is there a way to find the official "hierarchy" for each country? Also, if you happen to know the standards for Brazil or Mexico, feel free to clue me in.

Answer 1

This is tricky, since there are no global standards for addresses, and the mapping for the parts of the structured address (see the qualified input example) will need to match unless you invoke a fuzzy search using the &additionaldata=FlexibleAdminValues parameter.

Taking your use cases in turn, the simplest request and broadest set of results can be obtained using free form input as shown:

• 12 Avenida Sonora Iztapalapa

As you can see from the output, the label holds the postal address (which doesn't necessarily include all the hierarchy information), whereas the the State, County, City, District etc. hold the parts of the structured address (at least in the format that HERE has in its database). Therefore you can reduce the scope of a query by using the correct City or State in your query.

<Address>
    <Label>Sonora 12AV, Aculco, 09410 Iztapalapa, Distrito Federal, México</Label><Country>MEX</Country>
    <State>Distrito Federal</State>
    <County>Ciudad de México</County>
    <City>Iztapalapa</City>
    <District>Aculco</District>
    <Street>Sonora</Street>
    <HouseNumber>12AV</HouseNumber>
    <PostalCode>09410</PostalCode>
    <AdditionalData key="CountryName">México</AdditionalData>
    <AdditionalData key="StateName">Distrito Federal</AdditionalData>
</Address>

Since you already know the correct country, you can add &country=Mexico or &country=Brazil to restrict the search to one country (if you are not sure then use the countryfocus parameter to bias results towards that country instead.

A more restricted search can be made if the City or district etc. are known:

• city=Iztapalapa housenumber=12 street=Avenida Sonor (Note the typo)

This still finds a single result since sufficient information has been supplied.

So in summary, your best bet would be to try a few free-form searchText sample addresses in each country and see which fields are used by that nation before using structured addressing to reduce false positives in your results.

The XSD schema for Geocoding Results could also be useful to you especially the section on the MatchedAddressNamesType.