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

Entrypoint URI

/browse/by-corridor

Entrypoint Parameters

Parameter Type Description
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, if the route has more than 120 points or URL length is over 2000 characters, the corridor shortener endpoint should be considered to POST the route.

An alternative way to reduce URL length is to use Google's polyline encoding format. In this case the square brackets should be omitted. Width is supported in normal way. For example, route=_ky~H_oaoA?_ibE_th~C~mbJ;w=5000

cat Comma-separated list; required 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. Resources without an explicit category set will use an appropriate set of categories to find popular places within the given location context.
name String; optional Plain-text name of a place used to filter out the results. For example, "Brandenburger Tor"
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 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.
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 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]
        }
      }
    }
  }
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.