Places (Search) API Developer's Guide

Around Entrypoint

The Around Entrypoint represents sets of places within a specific location context, usually the location of the user. This Entrypoint is intended for applications that employ features such as augmented reality, where places around the user's location are displayed on a device. It is intended to provide places that are likely to be visible to the user as well as important places that are further away.

The Around Entrypoint allows users to request places near to a given point, based on a location precision parameter. The places around that point are returned in order of proximity.

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

Entrypoint URI

/discover/around

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.
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. Resources without an explicit category set will use an appropriate set of categories to find popular places within the given location context.
drilldown Boolean; optional If this flag is set to "true", result set will contain links to a further discover query based on the current query. For example result set may contain discover query links that restrict result set to a certain category (category drill down). To request a further drill down or in this case example, to expose subcategory filters on chosen discover query, application has to append the drilldown=true parameter to the chosen discovery query link.
Supported values are:
  • false
  • true
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 popular places for the given location context and matching the category filter criteria.

This method is intended for applications such as augmented reality, where places around the user's location are displayed on a device. It is intended to provide places that are likely to be visible to the user as well as important places that are further away.

Depending on the location context, the number of relevant places might be large. Therefore the GET method may not only return places, but also suggestions for additional filter criteria that allow users to interactively refine the classes of places they are interested in.

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/discover/around
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.50449,13.39091
&pretty

Response Example

{
  "search": {
    "context": {
      "location": {
        "position": [53, 14]
      }
    }
  },
  "results":{
    "items":[
      {
        "position": [52.498619, 13.37681],
        "distance": 1159,
        "title": "German Museum of Technology Berlin (Deutsches Technikmuseum Berlin)",
        "averageRating": 5,
        "category": {
          "id": "landmark-attraction",
          "title": "Landmark/Attraction",
          "href": "http://...",
          "type": "urn:nlp-types:category"
        },
        "icon": "http://...",
        "vicinity": "Trebbiner 9\n10963 Berlin\nGermany",
        "type": "urn:nlp-types:place",
        "href": "http://..."
        "id": "276u33d8-1cca7647c58a49d3a86b884a923ffa19"
      },
      {
        "title": "Eat & Drink",
        "icon": "http://...",
        "type": "urn:nlp-types:search",
        "href": "http://..."
      },
      {
        "title": "Going Out",
        "icon": "http://...",
        "type": "urn:nlp-types:search",
        "href": "http://..."
      },
      {
        "title": "Sights & Museums",
        "icon": "http://...",
        "type": "urn:nlp-types:search",
        "href": "http://..."
      }
    ]
  }
}