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 wego.here.com .
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.
Places API provides a possibility to get details of a place by Place ID.
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):
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 HERE
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:
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:
If the application has access to the user's position, it can send this as well:
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:
Places API provides a possibility to find a place by foreign ID.
Search for places in specified category along a route corridor.
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.
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:
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:
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.
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:
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:
Address search also finds post code areas. When searching in New York City, we can find Beverly Hills by just entering 90210:
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:
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:
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: