GuidesAPI Reference
Guides
  1. HERE Network Positioning API v2 Developer Guide
  2. Tutorials

How to find a position with WLAN

This section demonstrates how to obtain WGS-84 compliant geographical coordinates based on WLAN measurements.

Request position

Send a POST request and specify the request body content type in the HTTP headers. 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
📘

Note

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

This POST request requires a body with WLAN measurements formatted as specified in the API Reference.

For example, the body in this code block consists of WLAN information for six WLAN access points (APs), including their MAC-48 address (mandatory) and observed signal strength (optional).

📘

Note

For improved accuracy, it's recommended to always include signal strength information.

{
  "wlan": [
    {
      "mac": "74:26:AC:1F:47:9F",
      "rss": -47
    },
    {
      "mac": "74:26:AC:4C:5F:3E",
      "rss": -59
    },
    {
      "mac": "7C:21:0E:A9:58:03",
      "rss": -55
    },
    {
      "mac": "74:26:AC:1F:47:93",
      "rss": -57
    },
    {
      "mac": "7C:21:0E:A9:59:62",
      "rss": -59
    },
    {
      "mac": "7C:21:0E:A9:59:63",
      "rss": -59
    }
  ]
}

The response to the request contains following elements:

  • lat: WGS-84 latitude coordinate
  • lng: WGS-84 longitude coordinate
  • accuracy: radius of the uncertainty circle around the position in meters
{
  "location": {
    "lat": 61.49450804,
    "lng": 23.7754544,
    "accuracy": 4.0
  }
}

Request 3D position

You can also request a position estimate with altitude information.

Altitude information is requested by including the query parameter desired=altitude and is provided in the response if available.

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

With the same POST body as in the example above, the response to this request contains following items:

  • lat: WGS-84 latitude coordinate
  • lng: WGS-84 longitude coordinate
  • accuracy: radius of the uncertainty circle around the position in meters
  • alt: altitude in meters (referenced to the WGS-84 ellipsoid)
  • altAccuracy: uncertainty of the altitude estimate in meters
{
  "location": {
    "lat": 61.49450804,
    "lng": 23.7754544,
    "accuracy": 4.0,
    "alt": 138.9,
    "altAccuracy": 2.5
  }
}

Note that altitude can also be requested with the query parameter required=altitude. In this case, the request succeeds only if altitude information is available; otherwise, it fails with HTTP status code 404 Not Found. See the Construct Locate Request chapter for details.

Request with single WLAN

Precise positioning based on a single WLAN is not possible for privacy reasons. There has to be at least one other WLAN or serving cell object in the request with a matching location. Otherwise, the request fails with HTTP status code 400 Bad Request.

Alternatively, you can use the fallback query parameter with the singleWifi value to deliberately allow less accurate positioning based on a single WLAN. In that case, the center location of the position estimate will be deviated and the reported accuracy radius will be larger.

For example, using one of the WLANs from the requests shown above:

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

{
"wlan": [
{
  "mac": "74:26:AC:1F:47:9F",
  "rss": -47
}
]
}
📘

Note

If you decide to use this parameter, it's recommended to use it in all requests, not only those that contain a single WLAN measurement. This helps to avoid code 400 error responses when all WLANs except one have either a multicast MAC address or are otherwise unusable for position calculation.

This is a sample response:

{
  "location": {
    "lat": 61.491311,
    "lng": 23.769798,
    "accuracy": 519
  }
}

The response contains a much less accurate position estimate (both in terms of accuracy and center coordinate). Pairing a single WLAN with matching cellular data results in better accuracy.

Related Information

Updated last month