Positioning API Developer's Guide

Constructing a Request

A typical request to the Positioning API includes the basic elements shown in the following table and, in addition, it may contain resource-specific parameters or data.

Table 1. Basic request elements
Element	Value/Example	Description
Base URL	`https://pos.ls.hereapi.com`	Production environment when you use an API Key or an authentication token. For the full authentication story, see the Identity & Access Management Developer Guide.
Legacy Base URL	`https://pos.api.here.com`	Production environment when you use an app_id/app_code pair. For more information, see the Identity & Access Management Developer Guide.
Path	`/positioning/v1/`
Resource	`locate`	HTTPS POST only, submit data in the body of the request
HTTP header field	`Content-Type: application/json`	Used in both requests and responses.
HTTP header field	`Content-Encoding: gzip`	Optional header, indicates gzip encoded request body content
Application Code - Legacy	`&app_code={YOUR_APP_CODE}`	Substitute your own unique `app_code`. For more information, see the Identity & Access Management Developer Guide.
Application Id - Legacy	`&app_id={YOUR_APP_ID}`	Substitute your own unique `app_id`. For more information, see the Identity & Access Management Developer Guide.
API Key	`&apiKey={YOUR_API_KEY}`	Substitute with your own unique `apiKey`. For more information, see the Identity & Access Management Developer Guide.
HTTP header field	`Authorization: Bearer {YOUR_TOKEN}`	Authentication token. Not used in case of app_id + app_code or apiKey authentication. For more information, see the Identity & Access Management Developer Guide.
Desired	`&desired=altitude`	Comma-separated list of additional data fields that the service should include in the response, if the data is available. If requested data is not available, the response contains only default data fields. Available values are: `altitude` - request to include altitude fields in the response
Required	`&required=altitude`	Comma-separated list of additional data fields that the service has to include in the response. If requested data is not available, the request will fail. Available values are: `altitude` - request to include altitude fields in the response
Fallback	`&fallback=any\|area\|singleWifi`	Acceptable fallback options for cell and non-indoor WLAN positioning. Values 'area' and 'any' apply to cell based positioning, and value 'singleWifi' applies to outdoor WLAN based positioning. They may both be combined in the same request. By default cell based positioning returns cell tower level location estimates only. If you allow a WGS-84 compliant geocoordinate location estimate based on LAC, RNC, TAC, NID, or RZ areas, use the `fallback=area` setting. If you use the `fallback=any` setting, the service uses all available cell fallback methods and therefore the location estimate in the response may be at the MNC, SID, or MCC level. For privacy reasons precise positioning based on a single WLAN AP is not possible. You can use the `fallback=singleWifi` setting to allow less accurate positioning based on a single WLAN AP. In that case the center location of the position estimate will be deviated and the reported accuracy radius will be larger.
Confidence	`&confidence=50`	Confidence level in percent for the horizontal accuracy and, if requested, altitude accuracy, in the response location. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). Valid range is [50..98]

Here is an example of locate request, which uses API Key authentication:

POST https://pos.ls.hereapi.com/positioning/v1/locate?apiKey={YOUR_API_KEY}

Make sure to include request content type in the HTTP headers:

Content-Type: application/json

The POST body is as follows

{
  "wlan": [{
  "mac": "36:68:95:1A:36:93",
  "powrx": -74
  }, {
  "mac": "18:64:72:B7:BC:B2",
  "powrx": -75
  },{
  "mac": "18:64:72:B7:89:21",
  "powrx": -76
  },{
  "mac": "18:64:72:B7:BC:B1",
  "powrx": -77
  },{
  "mac": "18:64:72:B7:B1:63",
  "powrx": -79
  }]
}

Note: This example uses a HERE API Key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide.