Data Contribution API

Contribute data about WiFi access points and Cell towers.
Improved accuracy (and discounts!).

Documentation Examples

Start with a free developer token.

Data Contribution API v2 - Documentation

  1. Usage
  2. Request body
  3. Response body
  4. Examples

Usage

Requests are sent to the following endpoint:

https://d1.unwiredlabs.com/geosubmit.php?sbox=0&key=YOUR_API_KEY&id=DEVICE_ID
  • sbox - Sandbox. Must be set to 0 to submit data and 1 to test in sandbox. Defaults to 1.
  • key - Geosubmit API token.
  • id - Unique identifier of the device this data comes from.

Request body

Send the following data as a POST request in the 'JSON' format. (Fields are mandatory unless specified otherwise)
  • items - Array of observations. Send upto 50 positions in an 'item'. Each observation consists of one or more Cell or Wifi objects with the following parameters:
    • timestamp - The time of observation of the data, measured in milliseconds since the UNIX epoch (optional)
    • Position Fields - The position block contains information about where and when the data was observed.
      • latitude - The latitude of the observation (WSG 84).
      • longitude - The longitude of the observation (WSG 84).
      • accuracy - The accuracy of the observed position in meters.
      • altitude - The altitude at which the data was observed in meters above sea-level (optional)
      • altitudeAccuracy - The accuracy of the altitude estimate in meters (optional)
      • speed - The measured speed of the device in meters per second (optional)
      • heading - The direction of travel of the device in degrees (0° - 360°) clockwise relative to true north (optional)
    • cells - An array of cell ID objects.The first cell ID object has to be that of the serving cell, i.e. the tower the device is connected to. The others are neighbouring cell objects that are visible to the device.
      Parameters vary depending on the radio or network type:

      GSM - GSM, EDGE, GPRS, 2G

      • radio - Radio type of the device. Type: string; Value: gsm
      • mcc - Mobile Country Code of your operator's network. Type: integer
      • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer
      • lac - the Location Area Code of your operator's network. Type: integer; Range: 1 to 65533
      • cid - the Cell ID. Type: integer; Range: 0 to 65535
      • signal - the Signal strength (RSSI) of the radio, measured in dBm (Optional). Type: integer; Range: -51 to -113
      • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 0 to 31
      • tA - the Timing Advance value (Optional). Type: integer; Range: 0 to 63
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).

      CDMA - 1xRTT, CDMA, eHRPD, EVDO_0, EVDO_A, EVDO_B, IS95A, IS95B

      • radio - Radio type of the device. Type: string; Value: cdma
      • mcc - Mobile Country Code of your operator's network. Type: integer
      • mnc - the System ID (SID). Type: integer; Range: 1 to 32767
      • lac - the Network ID (NID). Type: integer; Range: 1 to 65534
      • cid - the Base ID (BID) or Station ID (SID). Type: integer; Range: 0 to 65535
      • signal - the Signal strength of the radio, measured in dBm (Optional). Type: integer; Range: -75 to -100
      • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 1 to 16
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).

      UMTS - UMTS, HSPA, HSDPA, HSPA+, HSUPA, WCDMA, 3G

      • radio - Radio type of the device. Type: string; Value: umts
      • mcc - Mobile Country Code of your operator's network (Optional). Type: integer
      • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer
      • lac - the Location Area Code of your operator's network. Type: integer; Range: 1 to 65533
      • cid - the Cell ID. Type: integer; Range: 0 to 268435455
      • signal - the Signal strength (RSCP) of the radio, measured in dBm (Optional). Type: integer; Range: -25 to -121
      • psc - the Primary scrambling code (Optional). Type: integer; Range: 0 to 511
      • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: -5 to 91
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).

      LTE - LTE, 4G

      • radio - Radio type of the device. Type: string; Value: lte
      • mcc - Mobile Country Code of your operator's network (Optional). Type: integer
      • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer
      • lac - the Tracking Area Code of your operator's network. Type: integer; Range: 1 to 65533
      • cid - the Cell ID. Type: integer; Range: 0 to 268435455
      • signal - Signal strength (RSRP) of the radio, measured in dBm (Optional). Type: integer; Range: -45 to -137
      • tA - Timing Advance value (Optional). Type: integer; Range: 0 to 63
      • pci - Physical Cell ID on LTE (Optional). Type: integer; Range: 0 to 503
      • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 0 to 97
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).

      NB-IoT (Public BETA)

      • radio - Radio type of the device. Type: string; Value: nbiot
      • mcc - Mobile Country Code of your operator's network. Type: integer
      • mnc - Mobile Network Code of your operator's network represented by an integer. Type: integer
      • lac - the Tracking Area Code of your operator's network. Type: integer; Range: 1 to 65533
      • cid - the Cell ID. Type: integer; Range: 0 to 268435455
      • pci - Equivalent to PCI in LTE. Some devices may report this as a NCID or Nb-IoT local cell id (Optional). Type: integer; Range: 0 to 503
      • signal - Signal strength (RSRP) of the radio, measured in dBm (Optional). Type: integer; Range: -45 to -137
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).

      New Radio - NR, 5G (Private BETA)

      • radio - Radio type of the device. Type: string; Value: nr
      • mcc - Mobile Country Code of your operator's network. Type: integer
      • mnc - Mobile Network Code of your operator's network. Type: integer
      • lac - Tracking Area Code or `TAC` of your operator's network. Type: integer; Range: 1 to 65533
      • cid - the Cell ID . Type: integer; Range: 0 to 68719476735
      • pci - Physical Cell ID or `PCI` (Optional). Type: integer; Range: 0 to 1007
      • signal - Signal strength (RSRP) of the radio, measured in dBm (Optional). Type: integer; Range: -44 to -140
      • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 0 to 97
      • serving - A value of 1 indicates this as the serving cell, a value of 0 indicates a neighboring cell. If omitted, the first cell is considered as the serving cell (Optional).
    • wifi - An array of WiFi objects visible to the device.
      • bssid - Base Service Set ID or MAC address of the Access Point
      • ssid - The SSID of the Wifi network (Optional)
      • channel - Channel the WiFi network is operating in (Optional)
      • frequency - Frequency the WiFi network is operating in, measured in MHz (Optional)
      • signal - Signal strength of the WiFi network, measured in dBm (Optional). Type: integer; Range: -51 to -113
      • signalToNoiseRatio - The current signal to noise ratio, measured in dB (Optional)
Notes:
  • Don't use leading zeroes in any of the above values without encapsulating that value in quotes, as it is invalid JSON and will return "Invalid Request".
  • Use double quotes (") not single quotes (') to encapsulate strings as per JSON standards.
{
    "items": [{
        "timestamp": 1480510819000,
        "position": {
            "latitude": 17.421189,
            "longitude": 78.400668,
            "accuracy": 10.0,
            "altitude": 100.0,
            "altitudeAccuracy": 50.0,
            "speed": 10.2,
            "heading": 35.5
        },
        "cells": [{
            "radio": "lte",
            "mcc": 405,
            "mnc": 854,
            "lac": 124,
            "cid": 315952,
            "serving": 1,
            "signal": -81
        }, {
            "radio": "lte",
            "mcc": 405,
            "mnc": 854,
            "lac": 2681,
            "cid": 55462,
            "signal": -87
        }],
        "wifi": [{
            "bssid": "92:2a:a8:95:ba:f7",
            "channel": 0,
            "frequency": 5180,
            "signal": -66
        }, {
            "bssid": "92:2a:a8:95:ba:f6"
        }]
    },
    {
        "position": {
            "latitude": 17.431189,
            "longitude": 78.410668,
            "accuracy": 50.0
        },
        "wifi": [{
            "bssid": "92:2a:a8:95:ba:f6"
        }]        
    },
    {
        "position": {
            "latitude": 17.451189,
            "longitude": 78.420668,
            "accuracy": 10.0
        },
        "cells": [{
            "radio": "lte",
            "mcc": 405,
            "mnc": 854,
            "lac": 124,
            "cid": 315952,
            "serving": 1,
            "signal": -81
        }]
    }
]}

Response body

Successful requests return a HTTP 200 response with an empty body.

Example scripts