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.
Use position, a visible map-view, categories and a free-text search query to discover places. The simplest case is the free text search query, which is provided by the discover/search resource. For example you might want to search for the famous Anthracite Coffee coffee-shop in Seoul:
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 in Seoul:
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.