Overview

Radar API allows you to calculate a device geolocation based on the information about its surroundings: observed cell towers and nearest Wi-Fi access points. This way you can determine probable device coordinates when the GPS signal is weak or missing. The following data can be used to calculate geolocation:

• Information about observed Wi-Fi access points.

  The number of Wi-Fi access points has the largest impact on positioning accuracy compared with other data.

• Information about observed cell towers.

  Cell towers of the LTE standard are preferred to base stations.

• Device geolocation data obtained from a GNSS receiver.

  GNSS position data is used anonymously to improve operation accuracy of the Radar API service.

The following factors impact positioning accuracy:

• Amount of data: the more Wi-Fi access points and cell towers are passed, the higher accuracy is achieved.
• Freshness of observed data: the less time has passed since the last observation of a Wi-Fi access point or a cell tower, the higher accuracy is achieved.

Radar API returns a radius and coordinates of a circle center where the device is located with high probability.

Getting an access key

Usage of this API requires an API key. To obtain the key:

1. Sign in to the Platform Manager.
2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.

In the Platform Manager, you can also:

• See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
• Set restrictions for a key by HTTP headers or by IP and subnet.
• Check the statistics of request distribution for each key.

Request example

To determine the device location, send a POST request to the https://radar.api.2gis.com/v1/geolocation endpoint. Specify your API key as the key parameter in the query string.

https://radar.api.2gis.com/v1/geolocation?key=API_KEY

Information about the surroundings and other parameters must be sent as a JSON string in the request body.

For example, to get a device location based on the information about one cell tower, one Wi-Fi access point, and a GNSS position, you can send the following request:

curl --request POST \
 --url 'https://radar.api.2gis.com/v1/geolocation?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
  "sessionUUID": "deea0dba-0000-41a1-a1b4-8b6fc342b07d",
  "captureTimestampUnix": 1628605467,
  "gnssLocation": {
    "latitude": 55.0302839,
    "longitude": 82.9231227,
    "horizontalAccuracyM": 6.228
  },
  "mobileNetwork": {
    "homeMobileCountryCode": 250,
    "homeMobileNetworkCode": 2,
    "cellTowers": [
      {
        "ageMs": 75002,
        "cellID": 138361350,
        "networkType": "lte",
        "locationAreaCode": 5401,
        "signalStrengthDBm": -101
      }
    ]
  },
  "wifiAccessPoints": [
    {
      "ageMs": 1000,
      "macAddress": "74:4d:28:2b:6c:32",
      "signalStrengthDBm": -75
    }
  ]
}'

Where:

• gnssLocation contains data about the device GNSS location: latitude, longitude, and positioning accuracy.
• mobileNetwork contains mobile county code, mobile network code, and information about the currently observed cell tower: time since the first observation, id, signal power, and more.
• wifiAccessPoints contains information about the currently observed Wi-Fi access point: time since the first observation, MAC address, and signal power.

You can find information about each field in API Reference.

Response example

The response returns an object containing the geolocation prediction: latitude, longitude, and a radius where the device is located with a probability of 68%. You can find information about each field in API Reference.

{
    "statusCode": 200,
    "state": "geoposition_located",
    "location": {
        "longitude": 82.92399186193771,
        "latitude": 55.02973009154781,
        "accuracy": 100
    }
}