How to construct a location request

A typical location request to the HERE Network Positioning API includes the basic elements shown in the following table.

Basic request elements

Request header

Location request is a HTTP POST request with body that contains the radio network measurements in JSON format. The request header must contain the target path, hostname, and content type. Additionally, you must authenticate with an API key or a bearer token.

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

{BODY} 

📘

Note

For the available authentication options, see the Identity and Access Management Developer Guide.

Request body

The request body must contain radio network measurements of at least one of supported types. For a complete list of the supported technologies, see Supported network technologies.

For example, this request contains LTE measurements (just single serving cell):

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

{
  "lte": [
    {
      "mcc": "262",
      "mnc": "02",
      "cid": 2898945
    }
  ]
}

Body compression

In many cases, in particular if WLAN measurements are included, the request body may get large. This service supports body compressed with gzip, deflate and br (Brotli) algorithms. If the body is compressed, you must specify the algorithm in the Content-Encoding header.

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

{BINARY DATA}

Successful response

If a request is successful, the HTTP response is 200 OK and the response body is a JSON object that includes the location estimate information.

• lat: WGS-84 latitude coordinate
• lng: WGS-84 longitude coordinate
• accuracy: radius of the uncertainty circle around the position, expressed in meters

{
  "location": {
    "lat": 61.4706194,
    "lng": 23.72265816,
    "accuracy": 829
  }
}

You can also request for altitude data. To learn more, see Desired output data.

Error response

Invalid input data

If you send a request body that's not compliant with the API specification, the response status code is 400 Bad Request and the body is a JSON object, which contains a description of the error. The most important fields are following:

• cause: reason for the error
• details: list of violated rules; can specify the part of the request, where the violated rule is found.

In the following example, the error response informs that the mcc field in the first item of the gsm measurements array in the body has invalid value. The details section further explains that the provided value exceeds the maximum allowed value and that it must be equal to or less than 999.

{
  "title": "Bad Request",
  "status": 400,
  "code": "E606400",
  "action": "Please correct the request and retry",
  "cause": "Validation error in body.gsm[0].mcc",
  "details": [
    {
      "title": "Violated rule: maximum",
      "message": "must be <= 999",
      "source": "body.gsm[0].mcc"
    }
  ]
}

To learn more about the expected body structure and the allowed value ranges for requests, see the API Reference.

Position not found

If location can't be estimated with the provided radio measurements (for example, because of inconsistent WLAN and cell information), the response status is 404 Not found.

{
  "title": "Not Found",
  "status": 404,
  "code": "E606404",
  "cause": "Position not found",
  "action": "The values provided in the request cannot produce any content for the response. The location of the WLANs and cells in the request is unknown or the locations of the radio measurements are so widely scattered that the location cannot be determined. Make sure that the network measurements are correct and consistent. Try allowing fallbacks `area` or `any` for cell positioning and `singleWifi` for WLAN positioning."
}

Request parameters

You can add query parameters to fine-tune the desired service behavior and response.

Desired output data

Use this parameter to get a comma-separated list of additional data fields that the service should include in the response if the data is available. If the requested data isn't available, the response contains only the default data fields.

POST /v2/locate?desired={VALUE} HTTP/1.1

You can request for the following data:

• altitude: include altitude data in the response

For an example, see Request 3-D position.

Required output data

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 with HTTP 404 Not Found status code.

POST /v2/locate?required={VALUE} HTTP/1.1

You can request for the following data:

• altitude: include altitude data in the response

Fallback modes

Acceptable fallback options for cell and WLAN positioning.

POST /v2/locate?fallback={VALUE} HTTP/1.1

Available values are: any, area and singleWifi.

The area and any values apply only to cell-based positioning and in case none of the models of the cells serving the target device are currently available. To learn more, see Cell fallbacks.

The singleWifi value applies to WLAN-based positioning in case only one of the provided WLAN access points (APs) can be used for position calculation. To learn more about WLAN fallback, see Requests with single WLAN.

Both cell and WLAN options may be specified in the same request:

POST /v2/locate?fallback=area&fallback=singleWifi HTTP/1.1

Alternatively, as a single query parameter:

POST /v2/locate?fallback=area,singleWifi HTTP/1.1

Confidence level

Confidence level for the horizontal accuracy and altitude accuracy (if altitude is requested) in the response location, expressed in percents.

POST /v2/locate?confidence={VALUE} HTTP/1.1

The allowed value range is [50..99].

If not specified, the default value is 68 which 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.

Examples

• Find Position with WLAN
• Find Position with Cell
• Find Position with Cell and WLAN

Related topics

• Supported network technologies
• Tips for optimizing data accuracy
• Identity & Access Management Developer Guide