Positioning API Developer's Guide

Locate

Request WGS-84 compliant geocordinates for a location based on 2G/3G/4G cell and/or WLAN measurements.

Request-model: observations_​locate

Request body containing cell and/or WLAN measurement data

Request Parameters

Name In Type Required Description
Content-Encoding header string , enum { gzip } Indicates the data in the body is gzip encoded. Value must be 'gzip'.
app_code query string required A 20-byte Base64 URL-safe encoded string used for the authentication of the client application.
app_id query string required A 20-byte Base64 URL-safe encoded string used for the authentication of the client application.
confidence query integer x ≥ 50 | x ≤ 99 Confidence level in percent for the accuracy/uncertainty in the location estimate response. 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 location estimate: the higher the number, the greater the confidence level).
desired query string Comma-separated list of additional data fields that the service should include in the response if data is available. The query parameter supports the value 'altitude'.
fallback query string Acceptable fallback level for cell based positioning. Use the default setting to accept 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 fallback methods and therefore the location estimate in the response may be at the MNC, SID, or MCC level. This parameter has no effect on WLAN based positioning. If the request contains both cell and WLAN measurements, this parameter only has an effect if no WLAN based position is found.
observations_locate body observations_​locate required Request body containing cell and/or WLAN measurement data
required query string Comma-separated list of additional data fields that the service should include in the response. If the data is not available, the response contains an error message. The query parameter supports the value 'altitude'.

Responses

Status Code Reason Description
200 OK response_​success_​locate Request processed successfully and a WGS-84 compliant geocoordinate location estimate was included in the response.
400 Bad Request response_​error The request is malformed. Check the message in the response for additional troubleshooting information. The URL query parameters or the JSON POST body in the request is invalid.
401 Unauthorized response_​error Authentication has failed due to incorrect credentials. Check your app_id and app_code.
403 Forbidden response_​error Authorization has failed. Access is not allowed with the app_id and app_code you provided.
404 Not Found response_​error 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.
500 Internal Server Error response_​error An unexpected server error has occurred, try again later.

Request Example

{
  "client": {
  "manufacturer": "Lemon",
  "model": "Flagship X1",
  "name": "FinderApp",
  "version": "2.0.31"
  },
  "lte": [
  {
    "mcc": 262,
    "mnc": 2,
    "cid": 2898945
  }
  ],
  "wlan": [
  {
    "mac": "F4-55-95-11-2C-C1"
  }
  ]
}

Response Example (200 OK)

{
  "location": {
  "location": {
    "lat": 61.4706194,
    "lng": 23.72265816,
    "accuracy": 829,
    "alt": 142,
    "altaccuracy": 20
  }
  }
}

Response Example (400 Bad Request)

{
  "error": {
  "code": 400,
  "message": "Bad Request",
  "description": "'mnc' must be less than or equal to 999"
  }
}

Response Example (401 Unauthorized)

{
  "error": {
  "code": 401,
  "message": "Unauthorized",
  "description": "The request is missing the app_id and app_code parameters. They must both be passed as query parameters. If you do not have app_id and app_code, please obtain them through your customer representative or at http://developer.here.com/myapps."
  }
}

Response Example (403 Forbidden)

{
  "error": {
  "code": 403,
  "message": "Forbidden",
  "description": "These credentials do not authorize access. Please contact your customer representative or submit a request here https://developer.here.com/contact-us to upgrade your account. You can also get valid credentials by registering for a free trial license on https://developer.here.com."
  }
}

Response Example (404 Not Found)

{
  "error": {
  "code": 403,
  "message": "Not Found",
  "description": "Position not found"
  }
}

Response Example (500 Internal Server Error)

{
  "error": {
  "code": 403,
  "message": "Not Found",
  "description": "Something unexpected happened. System administrators have been notified about the problem. Please try again later."
  }
}