GuidesAPI Reference
API Reference

Browse

This endpoint provides search results for places based on different filters, such as categories or name, ranked by distance from a given search center. The only mandatory elements exposed in the response are ID and position. The other elements shown in the response samples section are only dataset attributes suggestions.

Query Params
string
required

Specify the center of the search context expressed as coordinates

Required parameter for endpoints that are expected to rank results by distance from the explicitly specified search center

Format: {latitude},{longitude}

Type: {decimal},{decimal}

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

categories
array of strings

Category filter consisting of a comma-separated list of category-IDs for Categories defined in the HERE Places Category System, described in the Appendix to the HERE Search Developer Guide. Places with any assigned categories that match any of the requested categories are included in the response.

An exclamation mark "!" in front of a category ID causes that category to be excluded from the results. It is possible to mix excluded and included categories in the request - e.g. searching for places that are restaurants but not fast food restaurants. An exclusion will always win over an inclusion.

categories
chains
array of strings

Chain filter consisting of a comma-separated list of chain-IDs for Chains defined in the HERE Places Chain System, is described in the HERE Search Developer Guide Appendix. Places with any assigned chains that match any of the requested chains are included in the response.

An exclamation mark "!" in front of a chain ID causes that chain to be excluded from the results. It is possible to mix excluded and included chains in the request. For example, searching for results that are Amazon but not Wholefoods. An exclusion will always win over an inclusion.

chains
foodTypes
array of strings

FoodType filter consisting of a comma-separated list of cuisine-IDs for FoodTypes defined in the HERE Places Cuisine System, is described in the HERE Search Developer Guide appendix. Places with any assigned foodTypes that match any of the requested foodTypes are included in the response.

An exclamation mark "!" in front of a cuisine ID causes that foodType to be excluded from the results. It is possible to mix excluded and included foodTypes in the request. For example, searching for places that serve italian but not chinese. An exclusion will always win over an inclusion.

foodTypes
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:

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

Full-text filter on POI names/titles. Results with a partial match on the name parameter are included in the response.

string
enum

BETA

Selects the ranking mode to be used. This parameter only applies to places category, cuisine or chain search use cases (See browse-category-filter and browse-chain-filter). 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:
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)]
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
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.

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.

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
Headers
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

Language
Credentials
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json