Overview

Radar API allows you to determine an approximate device geolocation using Wi-Fi access points and cellular towers. You can use Radar API when the satellite signal is weak or unavailable (e.g., in urban areas, during signal jamming, or slow GNSS receiver startup), and other positioning systems perform poorly.

Important

Radar API determines the location with an accuracy of about 150-200 m in urban environments, so it does not replace satellite geopositioning and is not suitable for navigation scenarios that require high geopositioning accuracy.

Radar API returns a radius and coordinates of a circle center where the device is located with 68% probability. To calculate the location, Radar API uses the following data:

• Information about observed Wi-Fi access points. The number of Wi-Fi access points has the greatest impact on positioning accuracy compared to other data.
• Information about observed cellular towers. LTE standard cellular towers are preferred over base stations of other standards.
• Device location data obtained from the GNSS receiver. GNSS position data is used in anonymized form to improve the accuracy of Radar API.

The following factors impact positioning accuracy:

• Amount of data. The more Wi-Fi access points and cellular towers are provided, the higher the accuracy. In open areas where Wi-Fi access points are absent (e.g., on large highways), the positioning accuracy of Radar API is low.
• Data freshness. The shorter the time since the last observation of a Wi-Fi access point or cellular tower, the higher the accuracy.

Getting started

1. Get an access key

To work with the API of the service, you need to get an access key:

1. Sign in to the Platform Manager.
2. Create a demo key or purchase a subscription for using API.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Send a request

To determine the device location, send a POST request to the https://radar.api.2gis.com/v2/geolocation endpoint. Follow these steps:

1. In the request URL, specify the API key value for the key parameter:

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

2. In the request body, pass the JSON with the necessary parameters. For example, to get a device location based on the information about one cellular tower, one Wi-Fi access point, and a GNSS position, send the following request:

   curl --request POST \
   --url 'https://radar.api.2gis.com/v2/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 country code, mobile network code, and information about the currently observed cellular tower: time since the first observation, ID, signal power, and other parameters.
   • wifiAccessPoints contains information about the currently observed Wi-Fi access point: time since the first observation, MAC address, and signal power.

For more information about parameters, see the API Reference.

Response example:

The response returns an object with the predicted geolocation: latitude, longitude, and a radius where the device is located with 68% probability.

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

For more information about parameters, see the API Reference.