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

How to find a position with cellular data

This section shows how to get WGS-84 compliant geographical coordinates based on cellular network measurements.

Request cell-based 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 cellular network information formatted as specified in the API Reference. Serving cell information is mandatory in each measurement. For improved accuracy, it's recommended to always include neighbor cell measurements (in the optional nmr block) when available.

Below are a few examples for different cellular network technologies.

LTE

This code block demonstrates a POST request to obtain geographical coordinates using LTE measurements in the body. It consists of a single serving cell measurement with eight neighbor measurements.

{
  "client": {
    "manufacturer": "maker-of-the-device",
    "platform": "platform-of-the-device",
    "name": "client-name",
    "version": "1.1.10107",
    "model": "XYZ-123"
  },
  "contributions": [
    {
      "lte": [
        {
          "mcc": "460",
          "mnc": "099",
          "cid": 120072636,
          "tac": 65000,
          "localId": {
            "pci": 42,
            "earfcn": 10113
          },
          "ta": 1282,
          "rsrp": -140,
          "rsrq": -19.5,
          "nrCapable": true,
          "timestamp": "2021-01-01T14:15:33Z",
          "nmr": [
            {
              "pci": 43,
              "earfcn": 10113,
              "cid": 65484618,
              "rsrp": -50,
              "rsrq": -14
            },
            {
              "pci": 42,
              "earfcn": 10055,
              "cid": 65484484,
              "rsrp": -58,
              "rsrq": -15
            }
          ]
        }
      ],
      "position": {
        "type": "gnss",
        "lat": 39.914325,
        "lng": 116.316409,
        "accuracy": 5,
        "alt": 30,
        "altAccuracy": 60,
        "speed": 1,
        "course": 42,
        "satelliteCount": 9,
        "timestamp": "2021-01-01T14:15:34Z"
      }
    },
    {
      "lte": [
        {
          "mcc": 262,
          "mnc": 501,
          "cid": 120072635,
          "nmr": [
            {
              "pci": 0,
              "earfcn": 0
            },
            {
              "pci": 503,
              "earfcn": 262143
            }
          ],
          "timestamp": "2021-01-01T14:10:34Z"
        }
      ],
      "position": {
        "type": "gnss",
        "lat": 52.501608,
        "lng": 13.403481,
        "accuracy": 17,
        "alt": 68,
        "altAccuracy": 95,
        "speed": 5,
        "satelliteCount": 8,
        "course": 53,
        "timestamp": "2021-01-01T14:10:32Z"
      }
    }
  ]
}
📘

Note

The lte element is for LTE measurements only. LTE Cat-M cell measurements should be provided in the lteCatM element of the request body.

This is a sample response:

{
  "location": {
    "lat": 61.49539644,
    "lng": 23.78521015,
    "accuracy": 276
  }
}

This response contains horizontal geographical coordinates with following items:

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

LTE Cat-M

This code block demonstrates a POST request to obtain geographical coordinates using LTE Cat-M measurements in the body. It consists of a single serving cell measurement with four neighbor measurements.

{
  "client": {
    "manufacturer": "maker-of-the-device",
    "platform": "platform-of-the-device",
    "name": "client-name",
    "version": "1.1.10107",
    "model": "XYZ-123"
  },
  "contributions": [
    {
      "lteCatM": [
        {
          "mcc": "460",
          "mnc": "099",
          "cid": 120072636,
          "tac": 65000,
          "localId": {
            "pci": 42,
            "earfcn": 10113
          },
          "ta": 1282,
          "rsrp": -140,
          "rsrq": -19.5,
          "tech": "catM1",
          "timestamp": "2021-01-01T14:15:33Z",
          "nmr": [
            {
              "pci": 43,
              "earfcn": 10113,
              "cid": 65484618,
              "rsrp": -50,
              "rsrq": -14
            },
            {
              "pci": 42,
              "earfcn": 10055,
              "cid": 65484484,
              "rsrp": -58,
              "rsrq": -15
            }
          ]
        }
      ],
      "position": {
        "type": "gnss",
        "lat": 39.914325,
        "lng": 116.316409,
        "accuracy": 5,
        "alt": 30,
        "altAccuracy": 60,
        "speed": 1,
        "course": 42,
        "satelliteCount": 9,
        "timestamp": "2021-01-01T14:15:34Z"
      }
    },
    {
      "lteCatM": [
        {
          "mcc": 262,
          "mnc": 501,
          "cid": 120072636,
          "timestamp": "2021-01-01T14:10:34Z"
        }
      ],
      "position": {
        "type": "gnss",
        "lat": 52.501608,
        "lng": 13.403481,
        "accuracy": 17,
        "alt": 68,
        "altAccuracy": 95,
        "speed": 5,
        "satelliteCount": 8,
        "course": 53,
        "timestamp": "2021-01-01T14:10:32Z"
      }
    }
  ]
}

Standalone 5G NR (5G SA)

This code block demonstrates a POST request to obtain geographical coordinates using standalone 5G NR measurements in the body. It consists of a single 5G (NR) serving cell measurement with three 5G (NR) neighbor measurements.

{
  "nr": [
    {
      "mcc": "244",
      "mnc": "05",
      "tac": 23040,
      "cid": 3345838,
      "localId": {
        "nrarfcn": 641280,
        "pci": 729
      },
      "ss": {
        "rsrp": -69,
        "rsrq": -11
      },
      "nmr": [
        {
          "nrarfcn": 641280,
          "pci": 438,
          "ss": {
            "rsrp": -87,
            "rsrq": -17
          }
        },
        {
          "nrarfcn": 641280,
          "pci": 523,
          "ss": {
            "rsrp": -90,
            "rsrq": -17
          }
        },
        {
          "nrarfcn": 641280,
          "pci": 402,
          "ss": {
            "rsrp": -94,
            "rsrq": -19
          }
        }
      ]
    }
  ]
}

Non-standalone 5G NR (5G NSA)

This code block demonstrates a POST request to obtain geographical coordinates using non-standalone 5G NR measurements in the body. It consists of a single LTE serving cell measurement with three LTE neighbor measurements and three 5G NR neighbor measurements.

{
  "lte": [
    {
      "mcc": 244,
      "mnc": 91,
      "cid": 36847627,
      "localId": {
        "earfcn": 1300,
        "pci": 299
      },
      "ta": 9,
      "rsrp": -100,
      "rsrq": -11,
      "nmr": [
        {
          "earfcn": 1300,
          "pci": 341,
          "rsrp": -104,
          "rsrq": -16
        },
        {
          "earfcn": 1300,
          "pci": 241,
          "rsrp": -105,
          "rsrq": -17
        },
        {
          "earfcn": 1300,
          "pci": 480,
          "rsrp": -107,
          "rsrq": -15
        }
      ],
      "nrNmr": [
        {
          "nrarfcn": 156510,
          "pci": 127,
          "ss": {
            "rsrp": -110,
            "rsrq": -20,
            "sinr": -10
          },
          "csi": {
            "rsrp": -140,
            "rsrq": -20,
            "sinr": -23
          }
        },
        {
          "nrarfcn": 156510,
          "pci": 657,
          "ss": {
            "rsrp": -104,
            "rsrq": -15,
            "sinr": -2
          }
        },
        {
          "nrarfcn": 156510,
          "pci": 573,
          "ss": {
            "rsrp": -105,
            "rsrq": -17,
            "sinr": -4
          }
        }
      ]
    }
  ]
}

NB-IoT

This code block demonstrates a POST request to obtain geographical coordinates using NB-IoT measurements in the body. It consists of a single serving cell measurement with four neighbor measurements.

{
  "nbIot": [
    {
      "mcc": "244",
      "mnc": "05",
      "cid": 327691,
      "nrsrp": -81,
      "nmr": [
        { "earfcn": 3300, "pci": 7, "nrsrp": -86 },
        { "earfcn": 100, "pci": 143, "nrsrp": -93 },
        { "earfcn": 1825, "pci": 91, "nrsrp": -95 },
        { "earfcn": 3300, "pci": 93, "nrsrp": -100 }
      ]
    }
  ]
}

WCDMA

This code block demonstrates a POST request to obtain geographical coordinates using WCDMA measurements in the body. It consists of a single serving cell measurement with two neighbor measurements.

{
  "wcdma": [
    {
      "mcc": "262",
      "mnc": "07",
      "cid": 14674663,
      "rscp": -92,
      "nmr": [
        {
          "uarfcndl": 10786,
          "psc": 149,
          "rscp": -25
        },
        {
          "uarfcndl": 10762,
          "psc": 211,
          "rscp": -57
        }
      ]
    }
  ]
}

GSM

This code block demonstrates a POST request to get geographical coordinates by passing GSM measurements in the request body. It consists of a single serving cell measurement with five neighbor measurements.

{
  "gsm": [
    {
      "mcc": 262,
      "mnc": 1,
      "lac": 5126,
      "cid": 16504,
      "rxLevel": -32,
      "nmr": [
        { "bsic": 6, "bcch": 82, "rxLevel": -37 },
        { "bsic": 7, "bcch": 85, "rxLevel": -45 },
        { "bsic": 12, "bcch": 93, "rxLevel": -25 },
        { "bsic": 13, "bcch": 88, "rxLevel": -92 },
        { "bsic": 19, "bcch": 88, "rxLevel": -56 }
      ]
    }
  ]
}
📘

Note

MCC and MNC can be specified in a numeric form as shown in this code . However, it's recommended to use the string form, as shown in preceding examples. Using string allows for unambiguity as MNC codes "0x" and "00x" define different networks.

Request dual-cell position

On dual-SIM devices you can include cellular measurements from both modems into request. This example shows a request with both WCDMA and GSM information.

{
  "wcdma": [
    {
      "mcc": "262",
      "mnc": "07",
      "cid": 14674663,
      "rscp": -92,
      "nmr": [
        {
          "uarfcndl": 10786,
          "psc": 149,
          "rscp": -25
        },
        {
          "uarfcndl": 10762,
          "psc": 211,
          "rscp": -57
        }
      ]
    }
  ],
  "gsm": [
    {
      "mcc": "262",
      "mnc": "01",
      "lac": 5126,
      "cid": 16504,
      "rxLevel": -32,
      "nmr": [
        { "bsic": 6, "bcch": 82, "rxLevel": -37 },
        { "bsic": 7, "bcch": 85, "rxLevel": -45 },
        { "bsic": 12, "bcch": 93, "rxLevel": -25 },
        { "bsic": 13, "bcch": 88, "rxLevel": -92 },
        { "bsic": 19, "bcch": 88, "rxLevel": -56 }
      ]
    }
  ]
}

If both modems provide measurements of the same cell technology, they should be combined as shown in this example:

{
  "lte": [
    {
      "mcc": 262,
      "mnc": 2,
      "cid": 2898945
    },
    {
      "mcc": 262,
      "mnc": 1,
      "cid": 2106148
    }
  ]
}

Cell fallbacks

By default, cell based positioning returns only cell level location estimates. In LTE, LTE Cat-M, and 5G NR, use the fallback query parameter with value area if you permit location estimate to be based on a combination of cells of a single tower, or more precisely, on an eNodeB or gNodeB area. Also use this setting if you allow location estimate to be based on an area of a group of cells defined by the network (LAC, RNC, TAC, eNodeB, NID, or RZ). If you use the fallback query parameter with value any, the service can use all aforementioned cell fallback methods and additionally fallback to the MNC, SID, or MCC level. If both area and any are specified, then area is ignored.

For example, this request includes the wrong cell ID. Normally, it would fail with a 404 status and the cause "Position not found", but with fallback set to area it returns an estimate based on eNodeB.

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

{"lte": [{"mcc": 313, "mnc": 100, "cid": 190222336 }] }

The response is less accurate than normal LTE cell-based result:

"location": {
  "lat": 33.51999521,
  "lng": -82.3260498,
  "accuracy": 2394,
}

Related Information

Updated last month