Discover

post

https://example.com/discover

BETA, RESTRICTED

This endpoint processes a free-form text query for an address or place, and returns results in order of relevance.

Query Params

string

required

Enter a free-text query

Examples:

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

_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)

The following constraints apply:

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

fuelStation

object

BETA

Fuel Station attribute filters.

Combining multiple fuel type query parameters in a request constitutes requiring at least one of the specified filter conditions to be satisfied.

Example: fuelStation[fuelTypes]=biodiesel,ethanol,gasoline

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:

One of "at", "in=circle" or "in=bbox" is required.
Parameters "at", "in=circle" and "in=bbox" are mutually exclusive. Only one of them is allowed.
The "in=countryCode" parameter must be accompanied by exactly one of "at", "in=circle" or "in=bbox".

mobilityMode

string

enum

This field indicates the mode of mobility used by the end user when interacting with the Search service through the customer application. The information is used to improve the relevance of search results.

For example, a search for “EV charging station” will preferentially return charging stations suitable for trucks when the mobilityMode field is set to truck.

The mobilityMode field accepts a single value.

Description of supported values:

car: A standard motor vehicle primarily designed to transport up to 8 people, rather than cargo.
motorbike: A two-wheeled vehicle typically used by one or two people, suitable for commuting or long-distance travel.
truck: A larger vehicle primarily designed for transporting freight.

Allowed:

ranking

string

enum

BETA

Selects the ranking mode to be used. This parameter only applies to places category or chain search use cases (See discover-use-cases). It is ignored for other search use cases.

Description of supported values:

BETA excursionDistance: Rank results in along the route parameter by increasing distance from the route polyline.

Constraint: ranking=excursionDistance returns a 400 status code if the route parameter is not specified.

Allowed:

route

string

BETA

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

A route is defined by a Flexible Polyline Encoding, followed by an optional width, represented by a sub-parameter "w".

Format: {route};w={width}

In regular expression syntax, the values of route are formatted as follows:

[a-zA-Z0-9_-]+(;w=\d+)?

"[a-zA-Z0-9._-]+" is the encoded flexible polyline.

"w=\d+" is the optional width. The width is specified in meters from the center of the path. If no width is provided, the default is 1000 meters.

Type: {Flexible Polyline Encoding};w={integer}

The following constraints apply:

A route MUST contain at least two points (one segment).
A route MUST NOT contain more than 2,000 points.
A route MUST NOT have a width of more than 50,000 meters.

Examples:

BFoz5xJ67i1B1B7PzIhaxL7Y
BFoz5xJ67i1B1B7PzIhaxL7Y;w=5000
BlD05xgKuy2xCCx9B7vUCl0OhnRC54EqSCzpEl-HCxjD3pBCiGnyGCi2CvwFCsgD3nDC4vB6eC;w=2000

Note: The last example above can be decoded (using the Python class here as follows:

>>> import flexpolyline
>>> polyline = 'BlD05xgKuy2xCCx9B7vUCl0OhnRC54EqSCzpEl-HCxjD3pBCiGnyGCi2CvwFCsgD3nDC4vB6eC'
>>> flexpolyline.decode(polyline)
[(52.51994, 13.38663, 1.0), (52.51009, 13.28169, 2.0), (52.43518, 13.19352, 3.0), (52.41073, 13.19645, 4.0),
 (52.38871, 13.15578, 5.0), (52.37278, 13.1491, 6.0), (52.37375, 13.11546, 7.0), (52.38752, 13.08722, 8.0),
 (52.40294, 13.07062, 9.0), (52.41058, 13.07555, 10.0)]

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:

ALPHA, RESTRICTED recommendPlaces: The value "recommendPlaces" specifies that the endpoint ranks the results of place category search requests according to their importance and prominence, when this applies to the following categories: restaurant, coffee, supermarket, hotel, airport

with

evStation

object

evStation[<property>] deep object parameter allows adding constraints to the places results of category EV station (700-7600-0322, 700-7600-0323, 700-7600-0324). Search results of other types or categories will be returned without these constraints applied. Each property describes a separate constraint.

Currently, the following properties are supported:

evStation[minPower]: Sets a constraint on the minimum power in kW delivered by at least one of the station EVSE. Accepted is a single decimal value.
evStation[maxPower]: Sets a constraint on the maximum power in kW delivered by at least one of the station EVSE. Accepted is a single decimal value.
evStation[connectorTypeIds]: Sets a constraint on the connector type ID that the EV station result should have for at least one of its EVSE. Accepted are comma-separated integer values for non-deprecated connectors, listed in the HERE EV Charge Points API v2 documentation
evStation[supplierNames]: Sets a constraint on the charge point operator name operating of the EV station place result. Accepted are multiple comma-separated names.
evStation[current]: Sets a constraint on the current phase provided at one of the EVSE of the EV station result. Accepted is either AC or DC
evStation[eMobilityServiceProviderPartnerIds]: Sets a constraint on the e-Mobility Service Providers (eMSP) available at the EV station place result.
evStation[paymentMethodIds]: Sets a constraint on the payment methods that the EV station result should support.

Example (line-breaks used for the sake of readability):

evStation[connectorTypeIds]=29,33&evStation[minPower]=50.0&evStation[supplierNames]=ChargePoint&
evStation[eMobilityServiceProviderPartnerIds]=1f351b84-cca5-11ed-8155-42010aa40002&evStation[paymentMethodIds]=creditCard

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. For paginated queries (offset parameter) it specifies the expected number of results per page.

offset

int32

0 to 99

ALPHA

If set, the offset parameter switches on the pagination mode:

The response element items is returned together with the 4 attributes: limit, offset, count, nextOffset.
The response becomes a "page" of <count> results at a certain offset.
If offset parameter is not set, there is no pagination and none of the 4 attributes is returned.

Note that if the offset value exceeds the total number of items, the response items list will be empty.

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:

eMobilityServiceProviders: Returns for each place of category EV station (700-7600-0322, 700-7600-0323, 700-7600-0324) the list of e-Mobility Service Providers (eMSP) in extended.evStation field.
ev: Returns for each place of category EV station (700-7600-0322, 700-7600-0323, 700-7600-0324)
- connector groups details in extended.evStation field and
- detailed connectors availability in extended.evAvailability field.
Please note that the use of this option may impact latency.
phonemes: Renders phonemes for address and place names into the results.
referenceCategories: Renders the different place category identifiers associated with the reference information. Example: category identifier 600-6600-0082 (Garden Center) for the Yelp (TM) reference identifier -w_eNjJYsHVkt2UHRc3PDQ
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.
BETA, RESTRICTED fuel: Fetches fuel station related information if available and puts them in the extended.fuelStation field.
BETA, RESTRICTED fuelPrices: Fetches fuel prices related information if available and puts them in the extended.fuelStation field.

This option can only be used in combination with fuel or truck. Can also be used with both fuel and truck altogether.
BETA, RESTRICTED tripadvisor: If available, adds images, ratings, and editorials from Tripadvisor (TM) in the media field of place results.
BETA, RESTRICTED tripadvisorImageVariants: If available, adds the different image variants from Tripadvisor (TM) in the media field of place results. An image variants are details of the same image in various sizes (thumbnail, small, large, …)
BETA, RESTRICTED truck: Fetches truck station related information if available and puts the amenities in the extended.truckAmenities field.

show

Form Data

The request body must only contain those properties that are explicitly mentioned here. In general, those are query parameter that might contain especially long values, e.g. route. For POST requests those can alternatively still be supplied as query parameters. However, they must never be provided in both URL and request body simultaneously.

route

string

BETA

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

A route is defined by a Flexible Polyline Encoding, followed by an optional width, represented by a sub-parameter "w".

Format: {route};w={width}

In regular expression syntax, the values of route are formatted as follows:

[a-zA-Z0-9_-]+(;w=\d+)?

"[a-zA-Z0-9._-]+" is the encoded flexible polyline.

"w=\d+" is the optional width. The width is specified in meters from the center of the path. If no width is provided, the default is 1000 meters.

Type: {Flexible Polyline Encoding};w={integer}

The following constraints apply:

A route MUST contain at least two points (one segment).
A route MUST NOT contain more than 2,000 points.
A route MUST NOT have a width of more than 50,000 meters.

Examples:

BFoz5xJ67i1B1B7PzIhaxL7Y
BFoz5xJ67i1B1B7PzIhaxL7Y;w=5000
BlD05xgKuy2xCCx9B7vUCl0OhnRC54EqSCzpEl-HCxjD3pBCiGnyGCi2CvwFCsgD3nDC4vB6eC;w=2000

Note: The last example above can be decoded (using the Python class here as follows:

>>> import flexpolyline
>>> polyline = 'BlD05xgKuy2xCCx9B7vUCl0OhnRC54EqSCzpEl-HCxjD3pBCiGnyGCi2CvwFCsgD3nDC4vB6eC'
>>> flexpolyline.decode(polyline)
[(52.51994, 13.38663, 1.0), (52.51009, 13.28169, 2.0), (52.43518, 13.19352, 3.0), (52.41073, 13.19645, 4.0),
 (52.38871, 13.15578, 5.0), (52.37278, 13.1491, 6.0), (52.37375, 13.11546, 7.0), (52.38752, 13.08722, 8.0),
 (52.40294, 13.07062, 9.0), (52.41058, 13.07555, 10.0)]

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.

413Client error: request body exceeds size limit.

415Client error: request body has unsupported content type.

429Client error: Rate limit exceeded.

503Temporary server error.