Geocoder API Developer's Guide

Geocode Resource

This section contains a list of all Geocode request parameters.
.../6.2/geocode.{format}?<parameter>=<value>...
Table 1. Request Parameters
Parameter Description
additionaldata

Key-value pairs that provide additional input to requests. See Additional Data Parameter for a full list. Key and value are separated using a ,. Multiple key-value pairs are separated using a ;:

additionaldata=<Key1>,<Value1>;<Key2>,<Value2>;...

Example:

additionaldata=PreserveUnitDesignators,true;
  IncludeZipAddon,true
addressattributes

Comma separated list of which elements are present in the response data.

Enumeration [country, state, county, city, district, subdistrict, street, houseNumber, postalCode, addressLines, additionalData]

Abbreviated forms: [ctr, sta, cty, cit, dis, sdi, str, hnr, pst, aln, add]

On by default: All except addressLines.

Note: The value names are case-sensitive.

app_id

xs:string

A 20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request.  To get an app_id assigned to you, please see Acquiring Credentials.

app_code

xs:string

A 20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request.  To get an app_id assigned to you, please see Acquiring Credentials.

bbox

see also GeoBoundingBoxType

A type of Spatial Filter. A spatial filter limits the search for any other attributes in the request. A bounding box bbox is specified by two latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the second set the lower right. The bbox search is currently similar to mapview but it is not extended. Relevant global results are also returned.

bbox=<TopLeft.Latitude>,<TopLeft.Longitude>;
  <BottomRight.Latitude>,<BottomRight.Longitude>
Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965
city

xs:string, fuzzy match

A country specific mapping is required. Example,
  • USA: City
  • Germany: Gemeinde
country

xs:string, exact match

Specify the country or list of countries using the country code (3 bytes, ISO 3166-1-alpha-3) or the country name. This is a strict filter. Results are restricted to the specified country or countries.

Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO code and not with the spelled out country name. With names there is a higher risk of misspells and also not all language translations for all countries are supported.

countryfocus

xs:string, exact match, single ISO 3166-1-alpha-3 country code

Results from the specified country are preferred. This is a soft filter. Spelled out country names are not supported for country focus.
  • If both hard country filter and soft country focus parameter are set in the request the country filter takes precedence over the focus. This means results are limited to countries specified with country filter.
  • bbox or mapview filter take precedence over the country focus if there is a conflict.
county

xs:string, fuzzy match

Second subdivision level below the country. Depending on the admin hierarchy in a country this level might not be applicable. Example,
  • USA: County
  • Germany: Kreis
district

xs:string, fuzzy match

Subdivision level below the city. Depending on the admin hierarchy in a country this level might not be applicable. Example,
  • USA: n/a
  • Germany: Ortsteil
gen

xs:int

The gen parameter enables or disables backward incompatible behavior in the API. Please see details and the generation history in chapter Different Generations of the Same API. The latest generation is always recommended. This is currently gen=9.

housenumber

xs:string, exact match

The house number or house name.

jsonattributes

xs:int

If set to 1, the first character of each JSON response attribute name is set to lower case. Default value is 0.

jsoncallback

xs:string

Specifies the name of a user-defined function used to wrap the JSON response.

language

LanguageCodeType

The preferred language of address elements in the result. Language code must be provided according to RFC 4647 standard. Note that the plural form of the parameter (languages) is supported as well. But only the last specified language in the list is used. All preceding language preferences are ignored at this time.

locationattributes

Comma separated list of which elements are present in the response data.

Enumeration [address, mapReference, mapView, addressDetails, streetDetails, additionalData, adminIds, linkInfo, adminInfo, timeZone, addressNamesBilingual, related.nearByAddress]

Abbreviated forms: [ar, mr, mv, dt, sd, ad, ai, li, in, tz, nb, rn]

The adminIds switch is available with forward geocoding only.

For reverse geocoding results adminIds are always present unless turned off via locationattributes=none. locationattributes=-adminIds has no effect on reverse geocoding results.

The related.nearByAddress switch is available with the trackPosition mode of reverse geocoding only.

On by default for reverse geocoding: address, mapView, additionalData, mapReference, adminIds.

For forward geocoding: address, mapView, additionalData.

With mapReference link PVID, side of street, and admin area PVIDs are present in the response data. With adminIds only admin area PVIDs are present.

Note: The value names are case-sensitive.

locationid

xs:string, exact match

A key uniquely identifying a physical location. Each record in a geocode response contains a location Id. Use the Id to retrieve the exact same location information. For example, the location Id for "1 Market Street, 94105 San Francisco" is NT_NVpegjQLOBQa8ORYk3jV7A_xA.

mapview

See GeoBoundingBoxType

Specify the map coordinates of the app's viewport. The mapview is specified by two latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the second set the lower right. Matches from within the set map view plus an extended area are ranked highest. Relevant global results are also returned.

mapview=<TopLeft.Latitude>,<TopLeft.Longitude>;
  <BottomRight.Latitude>,<BottomRight.Longitude>
Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965
maxresults

xs:int

The number of items in the response structure can be limited. By specifying maxresults, the number of results per response are limited. When more results than the defined maximum are available, then these are returned on additional, separate pages. Each response contains a handle to the next page. For example, maxresults=5 returns a maximum of 5 results per page. If there were 8 results in total, the first page of five results indicates that there is a second page with more results.

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
pageinformation

xs:string

A key which identifies the page to be returned when the response is separated into multiple pages. Only relevant, if maxresults has been specified in a previous request and the response to the request includes the information that there is another page, for example:

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
politicalview

xs:string (3 bytes, ISO 3166-1-alpha-3)

Specify the political view. Available territories will be seen through the point of view of this country. If this parameter is not specified the neutral international view is made available, where territories may have unresolved claims.

For a complete list of supported views please see the appendix Political View.

For any political view that is unsupported the Geocoder falls back to the default view. For example, politicalview=USA or politicalview=FRA does not impact a response in any way.

postalcode

xs:string, exact match

Postal code defined by the government of the country.

prox

GeoProximityType, see also GeoProximityType

prox=lat,lon,radius

A type of SpatialFilter. A spatial filter limits the search for any other attributes on the request. Proximity specifies a circle to search using a latitude, a longitude, and a radius in meters. Search is similar to mapview. Matches from inside set area are ranked higher. Relevant global results are also returned.

responseattributes

Comma separated list of which elements are present in the response data.

Enumeration [performedSearch, matchQuality, matchType, matchCode, parsedRequest]

Abbreviated forms: [ps, mq, mt, mc, pr]

On by default: matchQuality, matchType

Note: The value names are case-sensitive.

searchtext

xs:string

searchtext contains free-form text containing address elements. You can specify the searchtext parameter by itself, or you can specify it with other parameters to narrow your search. For example, you can specify the state or country parameters along with a free-form address in the searchtext field. Please note that the searchtext should not include non-address related elements in order to improve the relevance of results.

state

xs:string, exact match

First subdivision level below the country. Specify state using full or abbreviated notation. A country specific mapping is required, for example
  • US: State
  • Germany: Bundesland
street

xs:string, fuzzy match

The street name can include suite, apt and floor information. When searching for a street intersection two formats are supported:
  • either using two parameters street0, street1, for example:
    street0=McAllister+St&street1=Market+St
  • or concatenating the two streets using one of the predefined separators ("and", "at", "&", or "@"), for example:
    street=McAllister+St+@+Market+St
strictlanguagemode

xs:boolean

  • True - if the value is available in the first language specified in the language parameter the attribute value is set directly in Address, Place, Location, and Category elements. Values in alternative languages are returned in the AlternativeValues element.
  • False - the best available attribute value based on the language priorities given in language parameter is returned directly in Address, Place, Location, and Category elements. No alternatives are returned.
token

xs:string

An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token is generated based on the user's app_id and received after the registration process of the application.

Parameter token is deprecated, use app_code instead.

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 selfservesupport@here.com.