Important context information is passed to the Places (Search) API using optional HTTP request headers. Wherever applicable the service relies on established and standardized headers, complementing these with some additional private headers. Some of these directly affect the results, while others help to optimize search results.
Note: Headers below are also accepted as GET url parameters of the same names. This functionality is provided only for developer convenience when experimenting with Places (Search) API in a web-browser. Production applications should not rely on this and should always send headers with each request as defined by HTTP standards.
Header NameDescription
Header Name
Description
Accept Specifies which media types are acceptable for the response (see Accept header specification ). This header is ignored for JSONP requests, which always have an application/javascript result media type. Defaults to application/json.
  • application/json results in a standard JSON response
  • application/xhtml+xml results in an XHTML representation of the JSON response in our playground UI
  • text/html results in an HTML representation of the JSON response in our playground UI
If the header is specified and no supported values are supplied, the result will be an HTTP 406 Not Acceptable error response.
Accept-Language The user or client's preferred languages (see Accept-Language header specification). This value is used to select the language of content in the response. Default: en.
Note: When different from default, the desired language must be specified in Accept-Language header with every request, including those originating from href links returned by Places (Search) API.
Date The user's local time, for example, Mon, 08 Aug 2011 11:58:17 GMT (see Date header specification).
User-Agent A string identifying the client user agent (see User-Agent header specification), used for statistical purposes. If the Places (Search) API is accessed from within a web browser, the browser should send this information automatically. For other applications, it may need to be explicitly set by the application.
Accept-Encoding Allows clients to enable compressed transfer of responses. The only supported value is gzip . Clients are strongly encouraged to make use of that option, as it can have a major impact on the responsiveness and performance of the client application (see Accept-Encoding header specification).
Geolocation The user's current position, formatted as a 'geo' URI as described in the Position Format documentation. (see HTTP Geolocation Internet-Draft). In the absence of an explicit location context, this is used to calculate the distance from the user returned in place results, and can act as an implicit location context. To ensure the best results possible, client applications should always send this header if it is able to determine the user's position.
X-Map-Viewport The bounding box of the map area currently visible to the user, formatted as described in the Bounding Box Format documentation. The viewport can act as an implicit location context in the absence of an explicit location context. To ensure the best results possible, client applications should always send this header if it is able to determine the user's position.
X-Mobility-Mode This header allows an application to indicate the user's means of transport, which can help Places (Search) API return better results:
  • walk indicates that the user is on foot. (DEPRECATED)
  • drive indicates that the user is driving.
  • public_transport indicates that the user is on public transport.
  • bicycle indicates that the user is on bicycle. (DEPRECATED)
  • none if the user is neither on foot nor driving.
X-MapVersion (DEPRECATED) If an application is using HERE map tiles and displaying a specific version of the tiles, the application can specify the map version using this header to ensure that returned place coordinates match the tiles you are using. The header value has the form map-type:map-version . For example, nlp-tiles:2.1, nlp-tiles:latest, or nlp-hybrid:8.0.47.117. If this header is not sent, Places (Search) API assumes nlp-tiles:latest.
X-NLP-Testing Used signal that a request is a test request, which won't influence our search relevance model.
  • 1 identifies the request as a test request.
  • 0 causes the request to be treated normally.
Defaults to 0.
X-Political-View Specify the political view. Available territories will be seen through the point of view of this country. If this parameter is not specified the neutral international view is made available, where territories may have unresolved claims. The country of the view is to be specified as ISO 3166-1-alpha-3 string.
X-VIN (DEPRECATED) If request originates from motor vehicle, this header can be used to specify the Vehicle Identification Number (VIN) as per ISO 3779
X-Fwd-App-ID (DEPRECATED) If a service is requesting Places (Search) API on behalf of a client application, the service must include the client's app_id in this header. To avoid double counting of the originating client app_id, follow-up calls should be done with a different app_id. This app_id should belong to the service who is calling Places (Search) API.
If the request is passing through several proxies, each proxy must append it's client app_id in this header. The leftmost element in this list holds information added by the first proxy, followed by information added by any subsequent proxy. For example, given a following request chain: Client → Proxy A → Proxy B → Places (Search) API.
  • Proxy A would request Proxy B with header X-Fwd-App-ID:"{YOUR_APP_ID}" and query parameter app_id={PROXY_A_APP_ID}.
  • Proxy B would then request Places (Search) API with header X-Fwd-App-ID:"{YOUR_APP_ID}, {PROXY_A_APP_ID}" and query parameter app_id={PROXY_B_APP_ID}.
Note: For internal use only!
X-NLP-TID If a service is requesting Places (Search) API on behalf of a client application, it is recommended that the service adds an unique transaction id in this header. If the service doesn't provide a transaction id, Places (Search) API will create an unique transaction id and includes it in the response header. Furthermore, the service should log and return the transaction id to the client. This allows tracking of one transaction across all involved systems.
Note: For internal use only!