Places (Search) API Developer's Guide

Browse by Corridor Entrypoint

The Browse by Corridor Entrypoint represent sets of places along a route area sorted by distance from starting point of the route.

The Browse by Corridor Entrypoint is a Places (Search) API Deprecated entrypoint.

Entrypoint URI

/browse/by-corridor

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

cat Comma-separated list; optional A comma-separated list of category ids defining an OR-filter that all places reachable through the resource must match. For a list of supported categories, see the Categories documentation.
name String; optional

Plain-text name of a place used to filter out the results. For example, "Brandenburger Tor"

The name parameter is mutually exclusive with the 'q' parameter.

urgency 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 for the given route 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. 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 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

Find petrol stations within a route corridor area between Berlin and Hamburg with 1 km off route distance.



In the following request example, URL encoding is omitted for better readability. An actual request would need to be URL encoded.

https://places.cit.api.here.com/places/v1/browse/by-corridor
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&route=[52.5160,13.3771|52.5111,13.3712|52.5355,13.3634|52.5400,13.3704|52.5626,13.3307|52.5665,13.3076|52.6007,13.2806|52.6135,13.2484|52.6303,13.2406|52.6651,13.2410|52.7074,13.1926|52.7045,13.0661|52.7191,12.9621|52.7636,12.8263|52.7861,12.8000|52.8335,12.7919|52.9002,12.7451|52.9708,12.6311|53.0526,12.5392|53.0867,12.5169|53.1146,12.4687|53.1334,12.4644|53.1415,12.4225|53.1666,12.3722|53.1785,12.3050|53.2570,12.1618|53.2893,12.0618|53.3000,11.9373|53.3316,11.8724|53.3463,11.8190|53.3669,11.7328|53.3725,11.6427|53.4154,11.5505|53.4309,11.4906|53.4342,11.4000|53.4655,11.3370|53.4873,11.2631|53.4860,11.2011|53.5110,10.9647|53.5128,10.8414|53.5495,10.6892|53.5692,10.5155|53.5596,10.4259|53.5682,10.2999|53.5571,10.2020|53.5672,10.1279|53.5534,9.9924];w=1000
&cat=petrol-station
&pretty

Response Example

{
  "results": {
    "items": [
      {
        "position": [52.53723, 13.37472],
        "distance": 277,
        "title": "Total",
        "averageRating": 0.0,
        "category": {
          "id": "petrol-station",
          "title": "Petrol station",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://...",
        "vicinity": "Chausseestraße 62<br/>10115 Berlin",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "http://...",
        "id": "276u33db-cc5a1377043842ba8fc3c6acd0b36e7d"
      },
      {
        "position": [52.542679, 13.37774],
        "distance": 822,
        "title": "Esso Station Mathias Fuhrmann",
        "averageRating": 0.0,
        "category": {
          "id": "petrol-station",
          "title": "Petrol station",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://...",
        "vicinity": "Gerichtstr. 4<br/>13347 Berlin",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "http://...",
        "id": "276u33db-be2f5afbd0e3458b9ad8410ed578fef7"
      },
      {
        "position": [52.53391, 13.36515],
        "distance": 839,
        "title": "Total",
        "averageRating": 0.0,
        "category": {
          "id": "petrol-station",
          "title": "Petrol station",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://download.vcdn.data.here.com/p/d/places2/icons/categories/18.icon",
        "vicinity": "Heidestraße 19<br/>10557 Berlin",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "http://...",
        "id": "276u33db-6bcb7b2e4fec41e9a295bba5709b00e4"
      },
      ...
    ],
    "search": {
      "context": {
        "location": {
          "position": [52.5353, 13.3773]
        }
      }
    }
  }
}