Places (Search) API China - BETA Developer's Guide

Filtering Searches by Location

The Places (Search) API China - BETA allows you to filter results when you can determine relevance by a specific location or by a location area. Provide the relevant location information in the form of location contexts. The Places (Search) API China - BETA supports the following kind of location contexts:
  • 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 at or 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 Geolocation and X‑Map‑Viewport. For more information on the available location context headers, see HTTP Request Headers.

You can also filter search results by category for relevance. For more information, see Filtering by Category.

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:

Name Availability Format Description
at Always Position Specifies an explicit position as a point
in Selected request types Circle or Bounding Box Specifies an explicit area

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:

Name Format Description
Geolocation Position Specifies the physical position of a user
X‑Map‑Viewport Bounding Box Specifies the map area currently displayed to the user

Best Practice

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.

Distance Calculation

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.

Position Format

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 cgen parameter:

  • map for points on a map, for example, geo:53.12,10.15;cgen=map.
  • gps for values from a GPS device, for example,geo:53.12,10.15;cgen=gps.
  • sgps for shifted GPS coordinates from a device fulfilling the legal requirements in China, for example, geo:53.12,10.15;cgen=sgps.

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.

Circle Format

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 13.125,52.362,13.661,52.693,4.3.