Places (Search) API Developer's Guide

Using free-text search

The discover/search resource uses the HERE place search engine to analyse queries that have been entered by users. It uses the location information as well as language information that is provided along with the query to try to understand the user intent. Generally it tries to be precise, i.e. return only results that are relevant to the query. Also, it tries to have good recall, i.e. return all the relevant results for a particular query.

Finding a specific place by it's name

A very basic use case is that the user is searching for a specific place, i.e. they know that it exists and want to find it. They might know its name and some location information. In this case the search engine orders the result according to how well they match the query. An example would be to search for the famous Brandenburg Gate in Berlin using a location in central Berlin:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=Brandenburg+Gate
&pretty

Finding faraway places

The search engine can find places even if they are not close to the coordinates that were provided. This is the case for places with name that are globally unique such as the Eiffel Tower. The following query will return the Eiffel Tower in Paris even though the application indicates that the location context is in Berlin:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=Eiffel+Tower
&pretty

The search engine also analyses the query for references to geographic names. So even though there are many museums in and around Berlin the following query will return the Science Museum in London, because London is mentioned in the query.

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=science+museum%2C+london
&pretty

Finding a place using its address

A common way to describe locations of places are addresses. The discover/search endpoint can also find addresses that are given as free-text user input. Even though we are providing the Berlin location the following address search will return the address in Hamburg, because it is specific enough to be interpreted without the extra location context:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=Rathausstraße+3%2C+Hamburg
&pretty

If the search string is less specific, it will take the location context into account. The following query will yield Rathausstraße 3 in Berlin, because we told the search engine that the location context is in central Berlin:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=Rathausstraße+3
&pretty

Address search also finds post code areas. When searching in New York City, we can find Beverly Hills by just entering 90210:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=40.7967,-73.9252
&q=90210
&pretty

Discovering a particular kind of place

In some cases users don't care about a specific place, they just need a particular kind of place, such as a cafe in a certain area. In this case the places are ranked according to the place rating, which is based on user interaction data and reviews. Here is an example to discover cafes in Berlin:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3843
&q=cafe
&pretty

For certain places a ranking by rating is not helpful, because they are interchangeable. Examples of such places include petrol stations, ATMs and different outlets of chain stores. Whenever the search engine detects such a query they result are ordered by distance. An example would be to search for a REWE supermarket near the HERE Berlin office:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3848
&q=REWE
&pretty

Restricting search results

It is possible to restrict search results within a search area. If you are not willing to walk for more than 500m for your restaurant, consider the following query:

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&in=52.531,13.3848;r=500
&q=restaurant
&pretty

Use your location

Additionally or alternatively to the explicit location context in the at and in parameter, an application can set implicit location contexts. If the application has a user-visible map it can send the viewport the user is currently looking at. The following example demonstrates a request with X-Map-Viewport header using curl command line tool.

curl \
--compressed \
-H 'Accept-Encoding:gzip' \
-H 'Accept-Language:en-US,en;q=0.8,de;q=0.6,id;q=0.4' \
-H 'X-Map-Viewport:13.3704,52.5122,13.4194,52.5262' \
--get 'https://places.cit.api.here.com/places/v1/discover/search' \
--data-urlencode 'app_id={YOUR_APP_ID}' \
--data-urlencode 'app_code={YOUR_APP_CODE}' \
--data-urlencode 'q=restaurant' \
--data-urlencode 'pretty=true'

If the application has access to the user's position, it can send this as well:

curl \
--compressed \
-H 'Accept-Encoding:gzip' \
-H 'Accept-Language:en-US,en;q=0.8,de;q=0.6,id;q=0.4' \
-H 'Geolocation:geo:52.531,13.3843' \
--get 'https://places.cit.api.here.com/places/v1/discover/search' \
--data-urlencode 'app_id={YOUR_APP_ID}' \
--data-urlencode 'app_code={YOUR_APP_CODE}' \
--data-urlencode 'q=restaurant' \
--data-urlencode 'pretty=true'

Refine search results

Setting the refinements parameter allows for retrieving places and refined searches. A refined search helps the search engine to deal with ambiguity in user queries. This allows the application to suggest refinements to the user's search.

https://places.cit.api.here.com/places/v1/discover/search
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.531,13.3848
&q=Paris+Bar
&refinements=true
&pretty

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.