Autocomplete

get

https://example.com/autocomplete

This endpoint completes entered keystrokes to a valid street address or administrative area to speed-up entering address queries.

Query Params

string

required

Enter a free-text query

Examples:

ber, berl, berli, ...
berlin+p, berlin+paris, berlin+parise, ...
berlin+pariser+20

Note: Whitespace, urls, email addresses, or other out-of-scope queries will yield no results.

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
a circular area, provided as latitude, longitude, and radius (in meters)

Format: circle:{latitude},{longitude};r={radius}

Type: circle:{decimal},{decimal};r={integer}

Example: circle:52.53,13.38;r=10000
a bounding box, provided as west longitude, south latitude, east longitude, north latitude

Format: bbox:{west longitude},{south latitude},{east longitude},{north latitude}

Example: bbox:13.08836,52.33812,13.761,52.6755

The following constraints apply:

Parameters "at", "in=circle" and "in=bbox" are mutually exclusive. Only one of them is allowed.

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:

types

array of strings

Limit the result items to the specified types.

Provide one of the supported values or a comma separated list.

Description of supported values:

address: restricting results to result types houseNumber, street, postalCodePoint, intersection
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), and interpolated, including exact house number matches and house number fallbacks
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

lang

array of strings

Select the preferred response language for result rendering from a list of BCP47 compliant Language Codes. The Autocomplete endpoint attemps to detect the query language based on matching name variants and then chooses the same language for the response.

The end-user is able to see and recognize all the entered terms in the same language as in the query. The specified preferred language is used only for unmatched address tokens and for matched address tokens in case of ambiguity

lang

limit

int32

1 to 20

Defaults to 5

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:

streetInfo: For each result item renders additional block with the street name decomposed into its parts like the base name, the street type, etc.
ALPHA, RESTRICTED hasRelatedMPA: For each result of type houseNumber with houseNumberType pointAddress, render a Boolean flag indicating whether sub-premises (Micro Point Addresses in HERE terms) are associated.

show

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.