Here Entrypoint
The Here Entrypoint helps users identify places at their location or at a point selected on a map by returning places close to a given point, sorted by distance. Normally the closest known places are returned, but if the uncertainty in the position is high then some nearer places are excluded from the result in favour of more popular places in the area of uncertainty.
This entrypoint can be used to help users answer questions like "Where am I?" and "What is at this point on the map?". You can use this endpoint to implement features like "check-in" (by identifying places at the user's current geo-position) or "click on map to get more information".
As with other entrypoints, the location to be used should be passed as a location context.
The Here Entrypoint is a Places (Search) API Deprecated entrypoint.
Entrypoint URI
/discover/here 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. |
| 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. Resources without an explicit category set will use the following default set of categories:
|
| 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:
|
| 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 |
| building | Comma-separated list; optional | A comma-separated list of 3D building ids defining an OR-filter that all places reachable through the resource must match., For example building=1,9000000000000870709. Building filter can be used for indoor navigation, e.g. searches in big shops/malls. Building Ids are available for clients who use Enterprise SDKs or have access to map content by other means. |
GET Method
The GET method provides access to popular places for the given location context and matching the category filter criteria.
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. Note: plain text can still be multiline. In this case newline symbol ("\n") is used to separate lines. Supported values are:
|
| 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.sit.ls.hereapi.com/places/v1/discover/here
?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://..."
}
]
}
}