Places (Search) API Developer's Guide

Search Entrypoint

The Search Entrypoint processes text string queries based on the user's input to find specific places. It answers questions of "what" and "where" for an online search of POI or address.

The results of the Search Entrypoint are sets of places that match a user's search term in a specific location context (such as near a given location, around a user's current position or on the currently visible map).

The Search Entrypoint is a Places (Search) API Core entrypoint.

Entrypoint URI


Entrypoint Parameters

Parameter Type Description
at Position (format: latitude,longitude[;cgen=(map|gps|sgps)][;u=\d+]); required, unless one of the Geolocation or X-Map-Viewport headers or the in are set.
Note: [;cgen=(map|gps|sgps)][;u=\d+] is DEPRECATED
Coordinates of search location expressed as latitude, longitude. Additional parameters can be passed which provide more context such as the uncertainty and how the coordinates were generated. For example, "52.5304417,13.4111201", "52.5304417,13.4111201;cgen=gps;u=100" or "52.5304417,13.4111201;u=100". For a full description, see the Location Contexts documentation.
q String; required Plain-text search term. For example, "restaurant" or "Brandenburger Tor"
in Area; required, unless one of the Geolocation or X-Map-Viewport headers or the at parameter are set. This parameter limits results to the boundary of the specified area. The search area can be expressed as:
  • circle specified as a centre point with latitude and longitude; and a radius around that point. Format: latitude,longitude;r=\\d+(\\.\\d+)?[;cgen=(map|gps|sgps)][;u=\\d+]
  • bounding box specified as 4 values, denoting west longitude, south latitude, east longitude, north latitude.
For a full description, see the Location Contexts documentation.
route Route (format: \[start(latitude,longitude|[width])|0..n(latitude,longitude|[width])|end(latitude,longitude[width])\][;w=\d+]); required

This parameter limits search results to the boundary of an area around a route. A route consists of a start coordinate, 0..n turning coordinates and an end coordinate. An optional width in meters can be passed to provide off the route max distance in meters, default: 1000m

The points should describe the geometric shape of the route with high precision. Especially, it’s usually not sufficient to only pass maneuvre points as they would be shown to the driver.

width specifier is CW or HW. It can follow any of the points to specify whether a route segment is located in a city or on a highway respectively, where segment is the point preceding specifier and following points till the next specifier. This will modify the search distance and possibly algorithm for the segment. DW will reset to default width (specified by w=\d+ ) and algorithm.

There are practical limitations to URL lengths. Thus, route parameters with more than 4700 characters will be rejected.

A way to reduce this parameter's length is to use a more space-efficient HERE polyline encoding and supply that as the compressedRoute parameter.

compressedRoute HereEncodedRoute (format: [a-zA-Z0-9._-]+(;w=\d+)?); required

This parameter is the new preferred way to specify a route. It contains the coordinates in HERE polyline encoding, which is basically a URL-safe version of Google's polyline encoding format.

Additionally, it may contain width attributes for individual parts of the route, i.e. one specify segments to have city width (.C), highway width (.H), or default width (.D).

By supplying the suffix ';w=\d+', one can define the actual width of the default width segments in meters.

addressFilter String; optional

Defines constraints used to filter results based on their address. Its value is a semicolon-separated list of key-value pairs. Each value can contain multiple options separated by a comma.

Key and value are separated by the equals sign. KeyValuePairType := [Key]=[Value]

Supported keys: countryCode (ISO 3166-1-alpha-3), stateCode, county, district, city, zipCode

Example: city=berlin,potsdam

recd (DEPRECATED) Boolean; optional; default: true.

For some endpoints, queries that describe recentering can be used. For example, if the search query is "Restaurants in München", then a recenter is inferred, and the implied search center is München. When this happens, a special result precedes the rest of the result items and describes the fact that a new search center was detected.

This parameter determines how distances to the returned results are reported. When the "recd" parameter is set to true, distances returned in the search results are calculated from the detected search center. When false, the distances are reported from the provided search center only. This parameter does not affect search results in any other way.

Supported values are:
  • false
  • true
asr (DEPRECATED) String (format: JSON); optional

Allows a query to be specified in an alternate way to the standard "q" parameter. The purpose of the "asr" parameter is to provide for easier integration with speech recognition systems. Such systems have two basic issues.

The first problem is that "asr" systems cannot distinguish between two words that spoken exactly the same way, e.g. "Marlboro" and "Marlborough". These are called "homophones".

The second problem is that speech recognition systems cannot easily distinguish between different phrases that sound nearly alike, e.g. "Metropolitan Museum" and "Metropolitan New Zealand". Such phrases are described as "phonetically similar". Speech recognition systems often provide a set of such phrases in a structure known as an "nbest list". Each list item has a phonetic score, and the list typically includes only the best matches, in many cases just one phonetic match.

The "asr" parameter is formatted in JSON and provides the following capabilities:

  • Queries are specified as an nbest list, with one or more list items. Each list item has a phonetic match score. The scores provided should be normalized such that the best phonetic match provided has a score of 1.0, and scores of the other list members range from 1.0 to 0.0. The number of list items provided in the "asr" parameter should be kept as small as reasonably possible - typically only one, but if necessary, 2 or 3.
  • Each nbest list item provided as part of an "asr" parameter can consist of either a single text striing, or of a list of tokens. When a list of tokens is provided, the "asr" parameter allows you to specify a full list of homophones and other phonetic possibilities for each token. Once again, there is a phonetic match score you must provide along with each token possibility, and the phonetic match score is normalized so that the best match has the score 1.0, while the other matches have scores that range from 1.0 to 0.0.

The nbest list mechanism in the "asr" parameter should be used as much as possible to distinguish between cases where different phonetic possibilities have different tokenization. When homophones or similiar-sounding terms are present, the tokenized possibility mechanism should be used preferentially.

Here is an example of an "asr" parameter which uses both n-best and homophone substitution capabilities. In this example, the user has said "Metropolitan Museum New York", but the speech recognition system has some difficulty distinguishing this with "Metropolitan New Zealand New York". Furthermore, in the case of "New", there are two distinct words that the speech recognition system knows about that sound exactly the same; these are "New" and "Nu". Finally, there's also another word in the system, "Netropolitan", that is similar enough phonetically to the word "Metropolitan" that it cannot be excluded as a possibility for what was said, so that too is provided.

  { "tokens": [ [ { "p": "Metropolitan", "s": 1.0 }, 
          { "p": "Netropolitan", "s": 0.9 } ],
          [ { "p": "Museum", "s": 1.0 } ],
          [ { "p": "New", "s": 1.0 },
          { "p": "Nu", "s": 1.0 } ],
          [ { "p": "York", "s": 1.0 } ]
        "score": 1.0 },
  { "tokens": [ [ { "p": "Metropolitan", "s": 1.0 },
          { "p": "Netropolitan", "s": 0.9 } ],
          [ { "p": "New", "s": 1.0 },
          { "p": "Nu", "s": 1.0 } ],
          [ { "p": "Zealand", "s": 1.0 } ],
          [ { "p": "New", "s": 1.0 },
          { "p": "Nu", "s": 1.0 } ],
          [ { "p": "York", "s": 1.0 } ]
         "score": 0.9 }

When this "asr" parameter is provided, the endpoint might return the following:

  • "title": "Metropolitan Museum of Art (Metropolitan Museum of Art - Cafeteria)"
  • "title": "Metropolitan Museum Art Shop"

Please note that the use of the "asr" parameter does not generally change the behavior of the endpoint that implements it. Instead, it only provides a different way of specifying the query, as an alternative to the "q" parameter. However, there are some differences worth noting. In the case of discover/search, the following caveats apply

  • The "asr" parameter cannot convert textual numbers into numerals; the speech recognition system is considered to be responsible for this. For example, the utterance "One hundred forty five" should be provided as the single token "145".
  • Block number plus house number utterances are also expected to be provided as a single token to the "asr" parameter. For example, "Forty three dash one forty four" should be provided as "43-144".
  • The Chinese language is currently not supported when using the "asr" parameter.
  • Phone number search is not supported.
  • Spell correction is not supported when the "asr" parameter is used, except insofar as provided explicitly by the user as different possibilities per token. This is because voice recognition systems cannot make spelling errors like a human would, and allowing spell correction would unnecessarily reduce the accuracy of the system.
  • Because of the practical limitations to URL lengths, it is not recommended to use this parameter in GET requests
urgency (DEPRECATED) Double; optional; default: 1.0.

This parameter is useful when search of interesting places along the route is performed and route parameter is specified.

There are two different ways of calculating distance along a route. The first way is to compute distance from where you are, along the route, and then perpendicular to the route. The second is to compute distance as the amount of extra travel needed to include the point in the route. The "urgency" parameter allows you to choose between the two, or choose a blending of the two. A value of 1.0 selects for distance along the route, and a value of 0.0 selects the amount of extra travel needed. Values in between weight each method correspondingly.

cs Comma-separated list; optional A comma-separated ordered list of category systems defining which type of category systems should be returned in the response. Valid category systems are 'places', 'cuisines', and 'pds'. For example cs=places,cuisines

GET Method

The GET method provides access to places matching the given term.

Representation Modifiers

The following options are available in this context:

Parameter Type Description
size Number (non-negative integer); optional The maximum number of result items in each collection.
tf String; optional; default: html. Text format. Determines how rich text properties such as location.address.text should be rendered. Note: plain text can still be multiline. In this case newline symbol ("\n") is used to separate lines.
Supported values are:
  • html
  • plain
show_refs (DEPRECATED) Comma-separated list; optional A list of one or more external system names or reference types. This parameter exposes place related external references in response. For a full description see Representation Modifiers documentation.
show_content (DEPRECATED) Comma-separated list; optional A list of one or more available content types you can add to the response. For a full description see Representation Modifiers documentation.

For additional information and examples, see Changing Responses with Representation Modifiers.

Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:search media type. See the urn:nlp-types:search media type documentation for details about the structure and content of the response.

Request Example

Response Example

  "search" : {
    "context" : {
      "title" : "Paris",
      "location": {
        "position": [48.85692,2.34121],
        "address": {
          "city": "Paris",
          "country": "France",
          "text": "Paris<br/>France"
        "type" : "urn:nlp-types:place"
    "results" : {
      "items" : [
        "position": [52.5031395, 13.3906403],
        "distance": 0,
        "title": "Wilhelm & Medne",
        "averageRating" : 5.0,
        "category": {
          "title": "Restaurant",
          "type": "urn:nlp-types:category",
          "href": "http://..."
        "icon": "http://...",
        "vicinity": "Hedemannstrasse 14<br/>10969 Berlin<br/>Germany",
        "href": "http://...",
        "type": "urn:nlp-types:place",
        "sponsored" : true,
        "id": "276u33d8-efb829f5b9464e5db8f286ff5fbf5643"
        "position": [52.5046, 13.39087],
        "distance": 11,
        "title": "Speakers Corner",
        "averageRating" : 0.0,
        "category": {
          "title": "Restaurant",
          "type": "urn:nlp-types:category",
          "href": "http://..."
        "icon": "http://...",
        "vicinity": "Friedrichstrasse 31<br/>10969 Berlin<br/>Germany",
        "href": "http://...",
        "type": "urn:nlp-types:place",
        "id": "276u33d8-b08d10d141e4405fbfdabbf017571401"