The HERE Places (Search) API uses location information to provide results that are as relevant as possible to your users. Location information is provided to the Places (Search) API in the form of location contexts. Location context information is either explicitly provided by the user, e.g. by clicking on a map, or is implicitly available to your application, such as the user's geoposition or the map viewport currently displayed to the user.
All HERE entry points require you to provide at least one location context. It is strongly recommended that you always provide all of the implicit location context information available to your application, and to additionally provide an explicit location context when the user action that triggers a request includes explicit location information. When the user does not explicitly indicate a location context, e.g. by performing a search query from a free-text input element, the best results are achieved by sending all available implicit location context and not sending any explicit location context parameters. See Best Practice for more detail about what location context to send.
Explicit Location Context
When the user explicitly indicates a location to your application, for example by clicking on a map position to trigger a discovery query at that location, your application should provide an explicit location context to the Places (Search) API using one of the following query string parameters:
| ||Always||Position||Specifies an explicit position as a point|
| ||Selected request types||Circle or Bounding Box or Polygon||Specifies an explicit area|
When an explicit location context is provided in this way, we recommend that you also send any applicable implicit location context information ( as described below). While the explicit location context will take precedence, providing additional implicit context information will ensure you get the best results possible.
Implicit Location Context
Your application will often have location information available to it that is not explicitly provided by the user, such as the user's geolocation or a map area currently being displayed to the user. Sending at least one type of implicit location context information is required in the absence of an explicit location context, and you are strongly encouraged to send implicit location context information to ensure you get optimal results even when providing an explicit location.
Applications should always send the following implicit location context headers when the values are known:
| ||Position||Specifies the physical position of a user|
| ||Bounding Box||Specifies the map area currently displayed to the user|
As an example of a case in which you should rely on implicit location context information alone, consider a user sitting on a train, browsing a map of their destination. Looking out of the window they see a castle and want to learn more about it, so they use your application's search function with a query of
castle. What is the most important piece of location context information for this search query? The user has not indicated an explicit location, and the most relevant location context could be the user's current location obtained from the device's GPS unit, or the location currently visible on the user's map. It is not obvious to the application which is the most relevant, and by providing all of the relevant implicit location context information to the Places (Search) API, it can try to determine and provide the most appropriate results.
To get the best results, applications should always send implicit location context information when available, and only send an explicit location context parameter when the user has explicitly indicated a specific location. Therefore, It is recommended that applications always send the
X-Map-Viewport header when the application is displaying a map to user, and always send the
Geolocation header when the user's position is known. This is sufficient in many use cases, and an explicit location context (via a query string parameter) is often not required.
For example, suppose the application always displays a map to the user, and provides a textbox for free-text search backed by the search entrypoint. If the user performs a search using this textbox, the application should supply the
X-Map-Viewport header, and if the user's position is also known, the
Geolocation header as well. The user hasn't indicated an explicit location related to their search (other than possibly positioning the map viewport), so there is no need to specify an explicit location context.
On the other hand, suppose the application also provides the ability to click on the map and find out what is at that location using the Here entrypoint. In this case, the user has an explicit location by clicking on the map, which the application should provide as an explicit location context in the
at query string parameter. The application should still send the implicit context information via the
X-Map-Viewport header (and the
Geolocation if the user's location is available), but the explicit location will take precedence for determining the primary location for the request.
Places in results have a distance field, which is intended to be the distance of that place from the user or from an explicit reference point. If an explicit location context is provided the distance will be calculated from the given position. In the absence of an explicit location context the position given in the Geolocation header is used. If the only available location context is from the X-Map-Viewport, no distances are returned.
The Geolocation header (implicit context) and
at parameter (explicit context) specify a position as a 'geo' URI. The position is given as comma-separated values for latitude and longitude (in the WGS 84 coordinate system), and optionally altitude (in meters above sea level), and a semicolon-separated list of position parameters.
Applications should specify the source for the position by passing one of the following values for the
mapfor points on a map, for example,
gpsfor values from a GPS device, for example,
sgpsfor shifted GPS coordinates from a device fulfilling the legal requirements in China, for example,
Uncertainty in the geo-coordinates should be given in the u parameter as the uncertainty in meters, for example,
geo:53.12,10.15;cgen=gps;u=100. This might be the uncertainty of a GPS coordinate fix, or uncertainty resulting from the resolution of a map. An absolutely accurate position should be specified with
u=0. If the u parameter is not provided, the uncertainty is unspecified rather than 0. For example,
39.91,116.40;cgen=gps;u=16 specifies a position derived from a GPS device with an uncertainty of 16 meters.
A circular area can be specified as a location context by providing a position (as described in Position) and an additional radius. The radius is given by setting the r parameter to the radius in meters. For example,
53.12,10.15;r=10500 specifies an area with a 10.5km radius.
Bounding Box Format
A bounding box can be used to specify a geographic area as a location context. The rectangle spanning the area is specified in the WGS 84 coordinate system as four comma-separated values in the following order: west longitude, south latitude, east longitude, north latitude. For example,
13.125,52.362,13.661,52.693 specifies a bounding box for Berlin.
For maps applications using HERE map tiles, the zoom level should be sent as a fifth parameter. For example, if the zoom level is 4.3, the above example would become
Polygon Format (Experimental)
A polygon area can be used to specify a location context by providing a set of at least four comma-separated coordinate pairs where the first and the last one are the same (see WGS 84 coordinate system) For example,
53.5869,10.0014,48.1305,11.5615,52.5171,13.3853,53.5869,10.0014 specifies a polygon area of Hamburg-Munich-Berlin.