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.

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.

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.

Browse by Corridor

Search for places in specified category along a route corridor.

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

Key-by-key prefix search

The browse/key-by-key resource uses a new here search engine that is geared towards use cases with small input bandwidth, such as in-car applications. It explicitly supports queries with partial tokens. This can save a lot of time, when the prefix of a token is already unique. Generally it behaves like the normal discover/search freetext search, i.e. it can find places and addresses, it supports queries for specific places or for places that belong to a certain catagory.

Here is an example searching from Berlin for a Hamburg using only the partial token "hamb". As Hamburg is an important result it is returned in front of more nearby places in Berlin, that have "Hamburg" in their name.

URL parameters

HTTP headers

Using multiple prefixes

Multiple prefixes can be used to restrict the search query. In the following example we are looking for the Hamburg city hall (German: Rathaus).

URL parameters

HTTP headers

High recall

Certain queries yield a large result set. Rather than trying to shorten the list and potentially hiding the desired result, key-by-key returns a the full set ordered by distance. An example is Jägerstraße.

URL parameters

HTTP headers

Locality of results

Generally queries are interpreted in the local context. Searching for Johannesburg from Berlin will thus yield a pub in Berlin's Friedrichshain district rather than the city in South Africa.

URL parameters

HTTP headers

If more context is provided places that are not close by are returned.

URL parameters

HTTP headers

Spelling correction

Key-by-key also supports spelling correction. The quality of the result depends on how close the mispelling is to the original spelling.

URL parameters

HTTP headers

Chains

Chain name prefixes will also be matched. The following query will find McDonald's outlets in Potsdam.

URL parameters

HTTP headers

Intersections

It is also possible to find street intersections, such as the one between Chausseestraße and Invalidenstraße in Berlin.

URL parameters

HTTP headers

X

Actions:

Actions:

Move map to: