Free-text Search
The discover/search resource uses the HERE place search engine to provide a list of places on the basis of a text string entered by the user. It uses the location information as well as language information that is provided along with the query to try to understand the request.
User Story
The user is in Berlin, Germany, and wants to find the Brandenburg Gate by name.
Request
Based on the user story, the information that can be provided to the search engine includes the location around which to search and the name of what to search for, "Brandenburg Gate". This indicates the possible query parameters to use.
The query parameter named at provides the explicit location context indicating that a geographically unrestricted search is to be conducted around a specific location. For example, &at=52.531,13.3843 sets the explicit location context to Invalidenstrasse near Nordbahnhof, Berlin, Germany.
An alternative is to restrict the search by using the parameter in instead of at. in confines the results to a radius around the location context. For example, &in=52.531,13.3848;r=500 defines both the location context and a radius of 500 meters.
A further possibility is to rely on implicit location contexts. For example, if the application displays map to the user, it can send the map viewport in the X-Map-Viewport header, otherwise, it can send the user's position in the Geolocation header.
q whose value is a text string. In this example, the goal is to search for "Brandenburg Gate", but the parameter is quite versatile and can otherwise hold:- a street address – for example,
Rathausstraße 3, Hamburg - a partial street address – for example, a street name and house number (in which case the user's current location is taken into consideration
- a post code – for example, "90210" or "SW4 1LD"
- the name of a remote landmark – for example, the user may be in Berlin, Germany, but search for the "Eiffel Tower"
- the name of a landmark and a geographic name – for example, "Science Museum, London"
- the name of place type – for example, "cafe", "museum"
- a commercial name – for example, "REWE" (supermarket chain)
- a telephone number – for example, +16175555555
Here is the complete query reflecting the user story:
https://places.ls.hereapi.com/places/v1/discover/search
?apiKey={YOUR_API_KEY}
&at=52.531,13.3843
&q=Brandenburg+Gate
&prettyResponse
The body of the response to the query contains the element "results" shown below – subject to modifications (see Examples) .
This response consists of the items, each representing a place. Depending on the type of query, the search engine will order the items by relevancy or distance. HERE Search relevancy takes into account multiple factors, including "popularity", distance, and term matching (see Search Results Ranking.
"results": {
"items": [
{
"position": [
52.5163,
13.37801
],
"distance": 23,
"title": "Brandenburg Gate",
"averageRating": 0,
"category": {
"id": "landmark-attraction",
"title": "Landmark/Attraction",
"href":
"https://places.ls.hereapi.com/places/v1/categories/places/landmark-attraction
?apiKey={YOUR_API_KEY}",
"type": "urn:nlp-types:category",
"system": "places"
},
"icon": "https://download.vcdn.data.here.com/p/d/places2_stg/icons/categories/38.icon",
"vicinity": "Pariser Platz<br/>Mitte, 10117 Berlin",
"having": [],
"type": "urn:nlp-types:place",
"href":
"https://places.ls.hereapi.com/places/v1/places/276u33db-8ee2e0de906e459cbade0593986debe9;
context=Zmxvdy1pZD1hNGU3ZjRkYy0yZWVhLTU1NGQtOTBhNC02ODM1NWI0ODc5NGNfMTQ4NDIzNTY4ODA1N185MDY...
?apiKey={YOUR_API_KEY}",
"id": "276u33db-8ee2e0de906e459cbade0593986debe9",
"authoritative": true
}
]
}