Filtering Searches by Location
- explicit – included in the request query parameters
Examples of explicit location contexts include providing a specific position, circle or bounding box based on user input by specifying a value for the query parameters
in. For more information on the available query parameters, see the API Reference.
- implicit – included in the request header
Examples of implicit location contexts include providing the current location from a device GPS unit or the map view displayed in the request header in the headers
X‑Map‑Viewport. For more information on the available location context headers, see HTTP Request Headers.
All Places (Search) API China - BETA entrypoints require at least one location context. We strongly recommend that you should always provide as much implicit location context information as possible and explicit location context information where relevant. For more information on best practices, see Best Practice.
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 China - BETA using one of the following query string parameters:
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:
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 (selected) a specific location. Therefore, applications should always send the
X-Map-Viewport header when displaying a map to user, and 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, if the application always displays a map to the user and provides a textbox for free-text search that makes use of the Places (Search) API China - BETA
search entrypoint. When the user performs a search, the application should supply the
X-Map-Viewport header. If the user's position is also known, the application should include the
Geolocation header as well. In this scenario, the user does not indicate an explicit location related to the search (other than possibly positioning the map viewport), so there is no need to specify an explicit location context.
If, however, the application additionally allows the user to click on the map and find out what is at that location using the
here entrypoint and the user does select a location in this way, the application should provide that location 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 takes precedence in determining the primary location for the request.
Places in results have a distance field indicating the distance from the user's location or from an explicit reference point to the place. An explicit location context in the request provides the location from which the distance is calculated. In the absence of an explicit location context, the position from the Geolocation header is used. If the only available location context is from the X-Map-Viewport, no distance calculation occurs and the distance is not set.
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