Places (Search) API Developer's Guide

Browse Entrypoint

The Browse Entrypoint represent sets of places within a specific location context sorted by distance.

The Browse Entrypoint allows users to request places around a given point. The Browse Entrypoint's location context might be an explicitly given location, it might be implicitly defined by a user's current position, or it might be implicitly defined by the currently visible map. Optionally, the places may be restricted to a given set of categories (which acts as a filter in terms of what places get returned).

at and in parameter are mutually exclusive and can't be passed at the same time

The Browse Entrypoint is a Places (Search) API Premium entrypoint.

Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

Entrypoint URI

/browse

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. 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.
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)|0..n(latitude,longitude)|end(latitude,longitude)\][;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.

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

A way to reduce this parameter's length is to use a more space-efficient Polyline encoding and supply that as the 'compressedRoute' parameter. For example, compressedRoute=ghxgK820xCze7kB00F_Es7LnxRg5F_5H;w=500

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.

name String; optional Plain-text name of a place used to filter out the results. For example, "Brandenburger Tor"
cat Comma-separated list; optional A comma-separated list of categorie ids defining an OR-filter that all places reachable through the resource must match. For a list of supported categories, see the Categories documentation.
result_types Comma-separated list of result type strings; optional A comma-separated list of the result types that should be included in the response. Possible values are: 'address' and 'place'. Address-only search is not supported at the moment, i.e. 'place' always has to be present. If this parameter is not set, only places are returned.
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. For example cs=places,cuisines

GET Method

The GET method provides access to places for the given location context and matching the category filter criteria.

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.
Supported values are:
  • html
  • plain
show_refs 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 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

https://places.cit.api.here.com/places/v1/browse
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&in=52.521,13.3807;r=2000
&cat=petrol-station
&pretty

Response Example

{
  "search": {
    "context": {
      "location": {
        "position": [52.521, 13.3807]
      }
    }
  },
  "results": {
    "items": [
      {
        "position": [52.528678, 13.36969],
        "distance": 1135,
        "title": "Steffen Kolberg Tankstellen Verwaltungs- und Betriebs GmbH",
        "averageRating": 0,
        "category": {
          "id": "petrol-station",
          "title": "Petrol station",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://...",
        "vicinity": "Heidestr. 65-68\n10557 Berlin",
        "type": "urn:nlp-types:place",
        "href": "http://...",
        "id": "276u33db-f2d1758f279348c1b134676cbcffdb81"
      },
      {
        "position": [52.533179, 13.37976],
        "distance": 1357,
        "title": "Total Station Inh. Hans-Jürgen Klasen",
        "averageRating": 5,
        "category": {
          "id": "petrol-station",
          "title": "Petrol station",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://...",
        "vicinity": "Chausseestr. 98\n10115 Berlin",
        "type": "urn:nlp-types:place",
        "href": "http://...",
        "id": "276u33db-dfb5ec1fed614c7fa7f10df85bf986cf",
      }
    ]
  }
}