Geocode

get

https://example.com/geocode

This endpoint allows you to find the geo-coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It also returns a complete postal address string and address details. It supports structured, unstructured and hybrid queries - combinations of structured and unstructured query elements.

Query Params

addressNamesMode

string

enum

This option allows users to choose between displaying normalized or matched address fields in the response, affecting the names in the address block, the address label, and the result title. This option is relevant when there is a difference between administrative naming and postal or common naming conventions, or when addressing with alternative street names. By default, geocoding results provide matched names for administrative places and normalized (official) names for street names.

Description of supported values:

matched: The service returns matched names for address fields.
normalized: The service returns normalized (primary) names for address fields.

Allowed:

addressNamesVariant

object

The deep‑object parameter enables the API to return different variants of the component names in the GS7 results.

Note: When both addressNamesVariant and addressNamesMode are specified, addressNamesVariant takes precedence.

string

Specify the center of the search context expressed as coordinates.

Format: {latitude},{longitude}

Type: {decimal},{decimal}

Example: -13.163068,-72.545128 (Machu Picchu Mountain, Peru)

string

Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified area.

A geographic area can be

a country (or multiple countries), provided as comma-separated ISO 3166-1 alpha-3 country codes

The country codes must be provided in uppercase.

Format: countryCode:{countryCode}[,{countryCode}]*

Examples:
- countryCode:USA
- countryCode:CAN,MEX,USA

postalCodeMode

string

enum

Options to return multiple results in areas where a postal code is associated with more than one district or city area. Without these options, the system only provides one result and may leave the district or city name blank or use a default name, potentially omitting relevant districts of cities.

Description of supported values:

cityLookup: When a postal code spans multiple cities, this option gives you all possible combinations of the postal code with the corresponding city names.
districtLookup: When a postal code spans multiple districts (within one city or across multiple cities), this option gives you all possible combinations of the postal code with the corresponding district and city names.

Allowed:

string

Enter a free-text query

Examples:

125, Berliner, berlin
Beacon, Boston, Hospital
Schnurrbart German Pub and Restaurant, Hong Kong

Note: Either q or qq-parameter is required on this endpoint. Both parameters can be provided in the same request.

string

Enter a qualified query. A qualified query is similar to a free-text query, but in a structured manner. It can take multiple sub-parameters, separated by semicolon, allowing to specify different aspects of a query.

Currently supported sub-parameters are country, state, county, city, district, street, houseNumber, and postalCode.

Format: {sub-parameter}={string}[;{sub-parameter}={string}]*

Examples:

city=Berlin;country=Germany;street=Friedrichstr;houseNumber=20
city=Berlin;country=Germany
postalCode=10969

Note: Either q or qq-parameter is required on this endpoint. Both parameters can be provided in the same request.

types

array of strings

A comma-separated list of the types that should be included in the response.

If this parameter is not set, all types are considered for the response.

Description of supported values:

address: restricting results to result types houseNumber, street, postalCodePoint, intersection, or addressBlock
area: restricting results to result types locality or administrativeArea including all the sub-types
city: restricting results to result type locality and locality type city
houseNumber: restricting results to result type: houseNumber, including house number types PA (Point Address), MPA (Micro Point Address) and interpolated, including exact house number matches and house number fallbacks
place: restricting results to result type place
postalCode: restricting results to postal codes: either result type postalCodePoint or result type locality with locality type postalCode.

Note that in Ireland and Singapore, where each address has unique postal code, postalCodePoint results are replaced by houseNumber results.
street: restricting results to result type street

types

with

array of strings

Activate certain features or consider specific kinds of results, that would not be active or provided by default.

Description of supported values:

RESTRICTED MPA: Enables the returning of Micro Point Address results. GS7 supports micro point addresses in the following countries: AUS, AUT, CAN, NZL, USA (with the territory of PRI).

with

lang

array of strings

Select the language to be used for result rendering from a list of BCP 47 compliant language codes.

lang

limit

int32

1 to 100

Defaults to 20

Maximum number of results to be returned.

politicalView

string

Toggle the political view.

This parameter accepts a single ISO 3166-1 alpha-3 country code in all uppercase.

If a valid 3-letter country code is provided for which GS7 does not have a dedicated political view, it will fallback to the default view.

The following political views are currently supported:

ARG: Argentina's view on the Southern Patagonian Ice Field and Tierra Del Fuego, including the Falkland Islands, South Georgia, and South Sandwich Islands
EGY: Egypt's view on Bir Tawil
IND: India's view on Gilgit-Baltistan
KEN: Kenya's view on the Ilemi Triangle
MAR: Morocco's view on Western Sahara
PAK: Pakistan's view on Jammu and Kashmir and the Junagadh Area
RUS: Russia's view on Crimea
SDN: Sudan's view on the Halaib Triangle
SRB: Serbia's view on Kosovo, Vukovar, and Sarengrad Islands
SUR: Suriname's view on the Courantyne Headwaters and Lawa Headwaters
SYR: Syria's view on the Golan Heights
TUR: Turkey's view on Cyprus and Northern Cyprus
TZA: Tanzania's view on Lake Malawi
URY: Uruguay's view on Rincon de Artigas
VNM: Vietnam's view on the Paracel Islands and Spratly Islands

show

array of strings

Select additional fields to be rendered in the response. Please note that some of the fields involve additional webservice calls and can increase the overall response time.

The value is a comma-separated list of the sections to be enabled. For some sections there is a long and a short ID.

Description of supported values:

countryInfo: For each result item renders additional block with the country info, such as ISO 3166-1 alpha-2 and ISO 3166-1 alpha-3 country code.
parsing
postalCodeDetails: For each result item of types postalCodePoint renders block with additional information about this postal code, such as postal code type: ZIP or ZIP+4; ZIP classification code: PO BOX, Unique or military; record type code for ZIP+4 codes. This feature is currently available only in the countries which are using ZIP codes - USA, PRI, VIR, GUM, MNP and ASM.
secondaryUnitInfo: For each matched unit designator, the geocode endpoint returns an additional block containing the normalized unit type and unit value. GS7 geocode currently supports normalized secondary unit info in the following countries: AUS, AUT, BRA, CAN, ESP, FRA, GBR, HKG, IDN, IND, MEX, NZL, TUR, TWN, USA (with the territory of PRI).
streetInfo: For each result item renders additional block with the street name decomposed into its parts like the base name, the street type, etc.
tz: Renders result items with additional time zone information.
ALPHA, RESTRICTED addressUsage: For each result item with types=houseNumber and houseNumberType=pointAddress, returns a flag indicating whether the address is residential.

show

showMapReferences

array of strings

Return the map references of the location objects

Description of supported values:

adminIds: Return the ids for the admin hierarchy of the response, to enable cross referencing into other services or data applications based on HERE Map Content
cmVersion: Return the core map version number of the region where the result is located
links: Return the link references from the result's access position, to enable cross referencing into other services or data applications
RESTRICTED microPointAddress: Return the reference of the micro point address, to enable cross referencing into other services or data applications based on HERE Map Content. This type of reference is only returned by Lookup endpoint or Geocode endpoint.
pointAddress: Return the reference of the point address, to enable cross referencing into other services or data applications based on HERE Map Content
segments: Return the street segment references from the result's access position, to enable cross referencing into other services or data applications based on HERE Map Content

NOTE The previous parameter show=hmcReference is deprecated and replaced by showMapReferences=segments which serves the same purpose.

showMapReferences

showNavAttributes

array of strings

Return requested additional attributes for segments in a road network if showNavAttributes parameter is specified with valid value and relevant data is available.

The value is a comma-separated list of the sections to be enabled.

Description of supported values:

access: Return the vehicle types allowed on a road or lane.
functionalClass: Return the functional class which is used to classify roads depending on the speed, importance and connectivity of the road.
physical: Return the values to describe special physical characteristics of a road.
speedLimits: Include speed limit and travel direction of the road in the results where available in content and when requested by the client application.

Note on speedLimits:
- The feature is not supported in Japan.
- This feature is subject to premium pricing. For details, contact your HERE customer representative.

showNavAttributes

showRelated

array of strings

allows enriching some types of response items with related items

Description of supported values:

RESTRICTED MPA: For type=houseNumber and houseNumberType=PA result items, include a block containing a list of micro point addresses associated to this address, such as buildings, floors (levels) or suites (units). GS7 supports micro point addresses in the following countries: AUS, AUT, CAN, NZL, USA (with the territory of PRI).
intersections: For street and house number results, include a block containing a list of intersections nearest to the address.
RESTRICTED parentPA: For type=houseNumber and houseNumberType=MPA result items, include a block containing the "parent" point addresses associated with this micro point address. GS7 supports micro point addresses in the following countries: AUS, AUT, CAN, NZL, USA (with the territory of PRI).

showRelated

showTranslations

array of strings

Shows translations and alternative names of the provided fields in all available languages.

This parameter accepts comma separated list of allowed fields for which translations are required.

Description of supported values:

city: shows alternative names and translations available for address field city
county: shows alternative names and translations available for address field county
district: shows alternative names and translations available for address field district
state: shows alternative names and translations available for address field state

showTranslations

Headers

X-Request-ID

string

Used to correlate requests with their responses within a customer's application, for logging and error reporting.

Format: Free string, but a valid UUIDv4 is recommended.

Responses

200The search results.

400Client error: request failed validation.

405Client error: http method not supported.

429Client error: Rate limit exceeded.

503Temporary server error.