x
clear

Invalid app_id app_code combination

Launch demo env | Register your own app

HERE Places API

The HERE Places API is a web service that allows your applications to use the HERE Places information and search facilities, as seen for example on here.com .

10 Minute Tutorial

This tutorial introduces the features of the Places API using examples for particular use cases. On the right-hand side of this tutorial page there are quick examples for each entrypoint, with all parameters pre-populated. The examples below each come with a form that contains the fields relevant for the use case being illustrated. Submitting that form calls an endpoint and displays the results in the playground view. The right-hand side of the playground view shows a pretty HTML rendering of the JSON response, while the left-hand side is a form with fields for tweaking all parameters supported by the endpoint.

The Places API is a REST API that serves hyper-media responses. Some functionality can be accessed through entrypoints that can be called directly, while other functionality is accessed by following links in the responses of previous calls.

The first example below is the first step in a very common flow: a search/discovery request is made, which returns a list of places, including links for more detailed information; a follow-up request can then be made using one of these links to get details for a place of the user's choosing. The diagram below illustrates typical API flows.

This is the Places API production environment. If you want to start playing around with the API you can
or
Set your own application info
Register your own application

Discover places

Use position, a visible map-view, categories and a free-text search query to discover places to build simple yet powerful user interfaces for place discovery. This feature is provided by the discover/search resource. For example you might want to search for the famous antipodes coffee shop in berlin (more examples are given below):

URL parameters

HTTP headers

If you look for a certain category of places that is supported by our category system, you might want to use the discover/explore endpoint. For example you might want to search for restaurants around the Nokia office in Berlin:

Also, it is possible to restrict the result of a discover/explore search to a radius. If you are not willing to walk for more than 500m for your restaurant, consider the following query:

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:

URL parameters

HTTP headers

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

URL parameters

HTTP headers

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.

beta

Tune result representation

The Places API offers a number of representation modifiers. If you want to restrict the number of search results, e.g. to 5, you might want to add the size parameter:

Lookup by foreign ID

Places API provides a possibility to find a place by foreign ID.

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 its name

A very basic use case is that the user is searching for a specific place, i.e. they know that it exists 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:

URL parameters

HTTP headers

Finding faraway places

The search engine can find places even if they are not close to the coordinates that were provided, e.g. as user position. 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 user is located in Berlin:

URL parameters

HTTP headers

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.

URL parameters

HTTP headers

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:

URL parameters

HTTP headers

If the search string is less specific, it will take the location context into account. The following query will yield Rathausstra├če 3 near Berlin's Alexanderplatz, because we told the search engine that the user is located in central Berlin:

URL parameters

HTTP headers

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

URL parameters

HTTP headers

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 certrain 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:

URL parameters

HTTP headers

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:

Guiding free-text entry with suggestions

Sometimes, especially in mobile use cases, it is not practical to force the user to type in the whole query. One way to deal with this is to use suggestions based on what the user has already entered. This partial matching is not quite as powerful and global as the search search engine, but it is a lot faster and uses less bandwith due to smaller responses, so that it can be invoked multiple times, while the user is typing more characters to refine the search. Here is an example for suggestions offered for "Madi" when standing in Bryant Park in New York, which will offer the nearby "Madison Ave" as a possible query:

URL parameters

HTTP headers

X

Actions:

Actions:

Move map to: