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.