Geocoder API Developer's Guide

Find Address Based on Complete or Partial Address Information using Qualified Input

If the address input is available in parsed form you can remove ambiguity by using specific fields for the address information. For example, a house number will never be mistaken for a postal code or a city name will not be interpreted as street name (San Antonio Rd in Palo Alto vs. the Palo Alto Rd in San Antonio). The following fields are available: country, state, county, city, district, postalcode, street, housenumber

An address search requires the street field, and either one or more of the locality type fields city and district or postalcode. The locality and postal code can be omitted if a user context such as a mapview is present.

Qualified input is aimed at geocoding business addresses where locality information is typically provided.

The house number can be provided in field housenumber or can also be attached to the street field. In the example below it is provided in its own field:

Qualified Input Example

The following example is a search for 425 W Randolph Street in Chicago and provides a fairly complete address as input.

The result is the same as the previous freeform input.

<Label>425 W Randolph St, Chicago, IL 60606, United States</Label>

City vs. District Match in Qualified Geocoding

If you are uncertain whether part of your address information is a city name or a district name you can specify that the service should return matches for both cases with the &additionaldata=FlexibleAdminValues,1 parameter.

The following example is a search for Friedrichstrasse in the city Mitte. But Mitte is actually a district of Berlin.

When you add the &additionaldata=FlexibleAdminValues,1 parameter the query returns the correct address.

  <Label>Friedrichstraße 100, 10117 Berlin, Deutschland</Label>
  <AdditionalData key="CountryName">Deutschland</AdditionalData>
  <AdditionalData key="StateName">Berlin</AdditionalData>

Combining Freeform with Qualified Input

Please note this option is for geocoding addresses and needs at least street level input to work as designed. It will not return expected results when the input is a named place only (e.g. city or district name).

Freeform and qualified input can also be combined. For example, a freeform search can be qualified with state or country information. The following example limits the search for Main St in Springfield to the state of Missouri. Without the state information a large number of matches in various states of the USA is returned.

Restricting the search to Missouri returns only one address.

<Label>Main St, Springfield, MO 65802, United States</Label>

state can be either a state code or name, and is not a strict filter, if no match is found in the specified state the response contains matches from other states.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on