Construct a Location Request

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

Basic request elements

Base URL

https://positioning.hereapi.com/v2

https://az.positioning.hereapi.com/v2

Production environment when you use an API Key or an authentication token. For the available authentication options, see the Identity & Access Management Developer Guide.

Path

/locate

Request for positioning.

HTTPS POST only, submit data in the body of the request.

API Key

&apiKey={YOUR_API_KEY}

Substitute {YOUR_API_KEY} with your own unique apiKey. For the available authentication options, see the Identity & Access Management Developer Guide.

Desired output data

&desired=altitude

Comma-separated list of additional data fields that the service should include in the response, if the data is available. If the requested data is not available, the response contains only default data fields.

Available values are the following:

• altitude - request to include altitude fields in the response

Required output data

&required=altitude

Comma-separated list of additional data fields that the service has to include in the response. If the requested data is not available, the request will fail.

Available values are the following:

• altitude - request to include altitude fields in the response

Fallback modes

&fallback=any|area|singleWifi

Acceptable fallback options for cell and WLAN positioning. Values area and any apply to cell based positioning, and value singleWifi applies to 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, the 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 level

&confidence=68

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].

Authentication Token

HTTP header:

Authorization: Bearer {YOUR_TOKEN}

Replace {YOUR_TOKEN} with your authentication token. For the available authentication options, see the Identity & Access Management Developer Guide.

Content Type

HTTP header:

Content-Type: application/json

Mandatory header. Used both in requests and responses.

Content Encoding

HTTP header:

Content-Encoding: gzip

Optional header, indicates gzip encoded request body content.

Example

The following is an example of the locate request that uses an API Key authentication. Make sure to include request content type in the HTTP headers.

POST /v2/locate?apiKey={YOUR_API_KEY} HTTP/1.1
Host: positioning.hereapi.com
Content-Type: application/json

POST /v2/locate?apiKey={YOUR_API_KEY} HTTP/1.1
Host: az.positioning.hereapi.com
Content-Type: application/json

The POST body is as follows

{
  "wlan": [
    { "mac": "A0:EC:F9:1E:32:C1" },
    { "mac": "A0:EC:F9:15:72:5E" },
    { "mac": "A0:EC:F9:15:72:5C" },
    { "mac": "A0:EC:F9:15:72:53" },
    { "mac": "A0:EC:F9:20:9D:AC" }
  ]
}

For more examples on location requests, see the following chapters:

• Find Position with Cell and WLAN
• Find Position with GSM
• Find Position with LTE
• Find Position with WCDMA
• Find Position with WLAN

Related Topics:

• Successful Locate Response
• Error Locate Response
• Identity & Access Management Developer Guide.