# TPS user beacon API request

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of user beacons (Wi-Fi access points and cell towers) scanned by the
                client.

**Endpoint URL**: [https://global.skyhook.com/wps2/json/user-beacon](https://global.skyhook.com/wps2/json/user-beacon)

**HTTP method**: POST

**Syntax**

    {
    "wifiAccessPoints": [...],
    "cellTowers": [...],
    }Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| :---: | --- | --- |
| `wifiAccessPoints` | – | List of entries corresponding to Wi-Fi<br>                                access points and their associated locations. |
| `cellTowers` | – | List of entries corresponding to cell<br>                                towers and their associated locations.<br>The contents of each entry<br>                                    depend on the type of cell tower: GSM, LTE, UMTS, WCDMA, CDMA,<br>                                    NB-IoT, NR. |

## Scanned Wi-Fi access points

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the Wi-Fi access points scanned by the
                client.

**Syntax**

    {
      "macAddress": "00:0C:41:82:D8:8C",
      "ssid": "network",
      "frequency": 2484,
      "location": {
        "lat": 42.351052,
        "lon": -71.049292,
        "alt": 35
    }
    Copy to clipboard

**Parameters**

| Parameter | Parameter | Values | Description |
| --- | --- | --- | --- |
| `macAddress` | `macAddress` | – | A string of hexadecimal characters representing a 6‑byte MAC<br>                                    address.<br>Pairs of hexadecimal characters are separated by<br>                                    colon (:). |
| `ssid` | `ssid` | – | (Optional) Service Set Identifier (SSID) of the access<br>                                point. |
| `frequency` | `frequency` | – | (Optional) Frequency of scanned Wi-Fi access point, in<br>                                MHz. |
| `location` | `location` | – | Location of the Wi-Fi access point. |
|  | `lat` | – | Latitude expressed in decimal degrees using floating point<br>                                values, using the WGS84 datum. |
|  | `lon` | – | Longitude expressed in decimal degrees using floating point<br>                                values, using the WGS84 datum. |
|  | `alt` | – | (Optional) Altitude of the Wi-Fi access point, in meters. |
|  |  |  |  |
|  |  |  |  |

## Scanned cell towers

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

The following syntax shows the fields that each cell tower can have in general, and
                each field may have a different meaning depending on the `radioType`.
                Each cell tower must contain either a `centroid` or an
                    `antenna` location element, which corresponds to the location of
                the cell tower.

**Syntax**

    {
      "radioType": "gsm",
      "mobileCountryCode": 722,
      "mobileNetworkCode": 310,
      "locationAreaCode": 8022,
      "cellId": 32508,
      "neighborId": 230,
      "channel": 40,
      "band": "GSM 480",
      "coverage": 35,
      "centroid": {
        "lat": 42.351052,
        "lon": -71.049292,
        "alt": 35
      },
      "antenna": {
        "lat": 42.358452,
        "lon": -71.044692,
        "alt": 25,
        "azimuth": 35.5,
        "vertTilt": 8.9,
        "beamWidth": 5.3,
        "vendor": "skyhook",
        "repeaterId": 1234
      }
    }
    Copy to clipboard

**Parameters**
Each `centroid` element
                can contain the following fields.

| Parameter | Values | Description |
| --- | --- | --- |
| `lat` | – | Latitude of the centroid expressed in decimal degrees using<br>                                floating point values, using the WGS84 datum. |
| `lon` | – | Longitude of the centroid expressed in decimal degrees using<br>                                floating point values, using the WGS84 datum. |
| `alt` | – | (Optional) Altitude of the cell tower location, in<br>                                meters. |

Each `antenna` element can contain the following
                fields.

| Parameter | Values | Description |
| --- | --- | --- |
| `lat` | – | Latitude of the centroid expressed in decimal degrees using<br>                                floating point values, using the WGS84 datum. |
| `lon` | – | Longitude of the centroid expressed in decimal degrees using<br>                                floating point values, using the WGS84 datum. |
| `alt` | – | (Optional) Altitude of the cell tower location, in<br>                                meters. |
| `azimuth` | Range: 0° to 360° | (Optional) Horizontal orientation of the antenna. |
| `vertTilt` | Range: 0° to 360° | (Optional) Vertical tilt of the antenna. |
| `beamWidth` | Range: 0° to 360° | (Optional) Beam width of the antenna. |
| `vendor` | – | (Optional) Vendor of the antenna; string. |
| `repeaterId` | – | (Optional) ID of the antenna repeater; integer. |

An additional optional field `antennaPos` can be submitted to
                indicate that the location is an antenna-based location. The
                    `antennaPos` element can contain the following fields.

Note: If `antennaPos` isn't supplied, the location is
                considered as centroid-based location.

| Parameter | Values | Description |
| --- | --- | --- |
| `azimuth` | Range: 0° to 360° | (Optional) Horizontal orientation of the antenna. |
| `vertTilt` | Range: 0° to 90° | (Optional) Vertical tilt of the antenna. |
| `beamWidth` | Range: 0° to 360° | (Optional) Beam width of the antenna. |
| `vendor` | – | (Optional) Vendor of the antenna; string. |
| `repeaterId` | – | (Optional) ID of the antenna repeater; integer. |

### GSM cell tower

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the GSM cell towers scanned by the
                client.

**Syntax**

    {
    "radioType": "gsm",
      "mobileCountryCode": 722,
      "mobileNetworkCode": 310,
      "locationAreaCode": 8022,
      "cellId": 32508,
      "neighborId": 230,
      "channel": 40,
      "band": "GSM 480",
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | – | Type of the cell tower. |
| `mobileCountryCode` | – | Indicates the mobile country code. |
| `mobileNetworkCode` | – | Indicates the mobile network code. |
| `locationAreaCode` | – | Indicates the local area code. |
| `cellId` | – | Indicates the cell ID. |
| `neighborId` | Range: 0 to 63 | (Optional) GSM BSIC composed of a 3‑bit network color code (NCC)<br>                                and a 3‑bit base station color code (BCC). |
| `channel` | – | (Optional) 16‑bit GSM channel number (ARFCN). |
| `band` | GSM 480 | (Optional) GSM band. |
| `coverage` | – | Radius of cell tower coverage, in meters. |

### UMTS/WCDMA cell tower

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the UMTS/WCDMA cell towers scanned by the
                client.

**Syntax**

    {
      "radioType": "UMTS",
      "mobileCountryCode": 730,
      "mobileNetworkCode": 2,
      "locationAreaCode": 63010,
      "cellId": 132105,
      "neighborId": 230,
      "channel": 40,
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | UMTS or WCDMA | Type of the cell tower. |
| `mobileCountryCode` | – | Indicates the mobile country code. |
| `mobileNetworkCode` | – | Indicates the mobile network code. |
| `locationAreaCode` | – | (Optional) Indicates the local area code. |
| `cellId` | – | `UMTS UC_ID` (combination of<br>                                        `RNDid` and `Cell_ID`) with a<br>                                    total of 28 bits as per 3GPP Technical Specification 25.401.<br><br><br>                                <br>Note: Populating cell ID with 16 bits may<br>                                    result in incorrect tower information. |
| `neighborId` | Range: 0 to 511 | (Optional) UMTS local cell ID (PSC). |
| `channel` | – | (Optional) 16‑bit UMTS channel number (UARFCN). |
| `coverage` | – | Radius of cell tower coverage, in meters. |

### LTE cell tower

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the LTE cell towers scanned by the
                client.

**Syntax**

    {
      "radioType": "lte",
      "mobileCountryCode": 730,
      "mobileNetworkCode": 2,
      "locationAreaCode": 63010,
      "cellId": 132105,
      "neighborId": 230,
      "channel": 40,
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | – | Type of the cell tower. |
| `mobileCountryCode` | – | Indicates the mobile country code. |
| `mobileNetworkCode` | – | Indicates the mobile network code. |
| `locationAreaCode` | – | (Optional) Indicates the LTE tracking area code (TAC). |
| `cellId` | – | LTE E-CGI (EUCID); 28 bits. |
| `neighborId` | Range: 0 to 503 | (Optional) ID of LTE local cell (PCI). |
| `channel` | – | (Optional) 18‑bit 3GPP channel number (EARFCN). |
| `coverage` | – | Radius of cell tower coverage, in meters. |

### CDMA cell tower

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the CDMA cell towers scanned by the
                client.

**Syntax**

    {
      "radioType": "cdma",
      "mobileNetworkCode": 2,
      "locationAreaCode": 63010,
      "cellId": 132105,
      "neighborId": 230,
      "channel": 40,
      "band": "CDMA 1800",
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | – | Type of the cell tower. |
| `mobileNetworkCode` | – | Indicates the CDMA system identifier (SID). |
| `locationAreaCode` | – | Indicates the CDMA network identifier (NID). |
| `cellId` | – | Indicates the CDMA base system identifier (BSID). |
| `neighborId` | Range: 0 to 511 | (Optional) ID of CDMA local cell (PNCODE). |
| `channel` | – | (Optional) 16‑bit CDMA channel number. |
| `band` | – | (Optional) CDMA band; string. |
| `coverage` | – | Radius of cell tower coverage, in meters. |

### NB-IoT cell tower

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the NB-IoT cell towers scanned by the
                client.

**Syntax**

    {
      "radioType": "nbiot",
      "mobileCountryCode": 730,
      "mobileNetworkCode": 2,
      "locationAreaCode": 63010,
      "cellId": 132105895657897,
      "neighborId": 230,
      "channel": 40,
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | – | Type of the cell tower. |
| `mobileCountryCode` | – | Indicates the mobile country code. |
| `mobileNetworkCode` | – | Indicates the mobile network code. |
| `locationAreaCode` | – | (Optional) Indicates the NB-IoT tracking area code (TAC). |
| `cellId` | – | NB-IoT cell ID; 28 bits. |
| `neighborId` | Range: 0 to 503 | (Optional) ID of NB-IoT local cell (NCID). |
| `channel` | – | (Optional) 18‑bit 3GPP channel number (EARFCN). |
| `coverage` | – | Radius of cell tower coverage, in meters. |

### NR tower (5G, New Radio)

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of entries corresponding to the 5G NR cell towers scanned by the
                client.

**Syntax**

    {
      "radioType": "nr",
      "mobileCountryCode": 730,
      "mobileNetworkCode": 2,
      "locationAreaCode": 63010,
      "cellId": 132105,
      "neighborId": 230,
      "channel": 40,
      "coverage": 1000
    }
    Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `radioType` | – | Type of the cell tower. |
| `mobileCountryCode` | – | Indicates the mobile country code. |
| `mobileNetworkCode` | – | Indicates the mobile network code. |
| `locationAreaCode` | – | (Optional) Indicates the 5G tracking area code (TAC). |
| `cellId` | – | 5G NR cell ID (NCI); 36 bits. |
| `neighborId` | Range: 0 to 1007 | (Optional) 5G local cell ID (PCI). |
| `channel` | – | (Optional) 24‑bit 3GPP channel number (NRARFCN). |
| `coverage` | – | Radius of cell tower coverage, in meters. |

## Scanned BLE beacons

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

The scanned Bluetooth low energy (BLE) beacon group allows the input of observed BLE
            beacons. Multiple BLE beacons and multiple types of BLE beacons are allowed as
            input.

BLE beacons can be submitted with the BLE type as a top-level element:

    {
      "wifiAccessPoints": [ .. ],
      "ibcnBleBeacons": [ .. ],
      "eddyStoneBleBeacons": [ .. ]
    }Copy to clipboard

### iBeacon BLE

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of iBeacon BLE beacons scanned by the client.

**Syntax**

    "ibcnBleBeacons": [
        {
          "uuid": "f7826da6-4fa2-4e98-8024-bc5b71eba31a",
          "major": 33834,
          "minor": 28699,
          "venueId": 144,
          "floorId": 166,
          "location": {
            "lat": 42.351052,
            "lon": -71.049292,
            "alt": 35
          },
          "altRef": "wgs84",
        }
      ]Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `uuid` | – | Universally Unique Identifier (ID1).<br><br><br>                                <br>Comprises 32 hexadecimal digits, split into 5 groups, separated<br>                                    by hyphens; 16 bytes.<br><br><br>                                <br>Format: 8-4-4-4-12 |
| `major` | Range: 0 to 65535 | Additional identifying number (ID2) assigned to iBeacon; unsigned<br>                                    integer. |
| `minor` | Range: 0 to 65535 | Additional identifying number (ID3) assigned to iBeacon; unsigned<br>                                    integer. |
| `venueId` | Default: 0 | Unique identifier of the venue; integer.<br><br><br>                                <br>The default is 0 if `venueId` isn't specified.<br><br><br>                                <br>To determine the value of `venueId`, see [TPS Indoor APIs](https://docs.qualcomm.com/doc/80-42204-2/). |
| `floorId` | Default: 0 | Unique identifier of the floor; integer.<br><br><br>                                <br>Specify `floorId` only if `venueId`<br>                                    is specified. The default is 0 if `venueId` isn't<br>                                    specified.<br><br><br>                                <br>To determine the value of `floorId`, see [TPS Indoor APIs](https://docs.qualcomm.com/doc/80-42204-2/). |
| `location` | – | Location of the BLE beacon access point.<br><br><br>                                <br>A location has the following fields:<br><br><br>                                <ul class="ul" id="ibeacon-ble__ul_zfw_k4k_bjc"><br>                                    <li class="li"><code class="ph codeph">lat</code>: Latitude, WGS84 datum representation;<br>                                        floating point.</li><br><br>                                    <li class="li"><code class="ph codeph">lon</code>: Longitude, WGS84 datum representation;<br>                                        floating point.</li><br><br>                                    <li class="li"><code class="ph codeph">alt</code>: (Optional) Altitude, in meters, of the<br>                                        Wi-Fi access point; floating point.</li><br><br>                                </ul> |
| `altRef` | – | A specific, established vertical datum plane that's a reference<br>                                    point for measuring `alt` accurately.<br><br><br>                                <br>Supported values are:<br><br><br>                                <ul class="ul" id="ibeacon-ble__ul_krc_wpk_bjc"><br>                                    <li class="li">WGS84</li><br><br>                                    <li class="li">Mean sea level (MSL)</li><br><br>                                    <li class="li">Above ground level (AGL)</li><br><br>                                    <li class="li">AGL Digital/derived floor/field</li><br><br>                                </ul> |

### Eddystone BLE

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

Provides a list of Eddystone BLE beacons scanned by the client.

**Syntax**

    "eddyStoneBleBeacons": [
        {
          "namespaceId": "f7826da6bc5b71e0893e",
          "instanceId": "abcd1234efgh",
          "venueId": 144,
          "floorId": 166,
          "location": {
            "lat": 42.351052,
            "lon": -71.049292,
            "alt": 35
          }
        }
      ]Copy to clipboard

**Parameters**

| Parameter | Values | Description |
| --- | --- | --- |
| `namespaceId` | – | 20‑byte hexadecimal identifier (ID1); string. |
| `instanceId` | – | 12‑byte hexadecimal identifier (ID2); string. |
| `venueId` | Default: 0 | Unique identifier of the venue; integer.<br><br><br>                                <br>The default is 0 if `venueId` isn't specified.<br><br><br>                                <br>To determine the value of `venueId`, see [TPS Indoor APIs](https://docs.qualcomm.com/doc/80-42204-2/). |
| `floorId` | Default: 0 | Unique identifier of the floor; integer.<br><br><br>                                <br>Specify `floorId` only if `venueId`<br>                                    is specified. The default is 0 if `venueId` isn't<br>                                    specified.<br><br><br>                                <br>To determine the value of `floorId`, see [TPS Indoor APIs](https://docs.qualcomm.com/doc/80-42204-2/). |
| `location` | – | Location of the BLE beacon access point.<br><br><br>                                <br>A location has the following fields:<br><br><br>                                <ul class="ul" id="eddystone-ble__ul_zfw_k4k_bjc"><br>                                    <li class="li"><code class="ph codeph">lat</code>: Latitude, WGS84 datum representation;<br>                                        floating point.</li><br><br>                                    <li class="li"><code class="ph codeph">lon</code>: Longitude, WGS84 datum representation;<br>                                        floating point.</li><br><br>                                    <li class="li"><code class="ph codeph">alt</code>: (Optional) Altitude, in meters, of the<br>                                        Wi-Fi access point; floating point.</li><br><br>                                </ul> |
| `altRef` | – | A specific, established vertical datum plane that's a reference<br>                                    point for measuring `alt` accurately.<br><br><br>                                <br>Supported values are:<br><br><br>                                <ul class="ul" id="eddystone-ble__ul_krc_wpk_bjc"><br>                                    <li class="li">WGS84</li><br><br>                                    <li class="li">Mean sea level (MSL)</li><br><br>                                    <li class="li">Above ground level (AGL)</li><br><br>                                    <li class="li">AGL Digital/derived floor/field</li><br><br>                                </ul> |

## Support for expiration date and TTL

Source: [https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html](https://docs.qualcomm.com/doc/80-42223-1/topic/user_beacon_api_request.html)

The TPS user beacon API now supports expiration date and time-to-live (TTL). This
                functionality is implemented both at the top level of JSON request and beacon level
                (AP or cell tower).

Note: OEMs can choose to use either expiration date or TTL for a
                beacon type but not both.

**Syntax**

    {
      "apExpirationDate": "2023-03-17", 
      "apTtl": 30, 
      "cellExpirationDate": "2023-03-17", 
      "cellTtl": 100, 
     
     "wifiAccessPoints": [
        {
          "macAddress" : "00:0C:41:82:D8:8C",
          "ssid": "network",
          "frequency": 2484,
          "location": {
            "lat": 42.351052,
            "lon": -71.049292,
            "alt": 35
          },
          "expirationDate": "2023-03-17" 
          "ttl": 60 # 
       }
     ],
      "cellTowers": [
       {
          "radioType": "gsm",
          "mobileCountryCode": 722,
          "mobileNetworkCode": 310,
          "locationAreaCode": 8022,
          "cellId": 32508,
          "neighborId": 230,
          "channel": 40,
          "band": "GSM 480",
          "coverage": 35,  
          "antenna": {
            "lat": 42.351052,
            "lon": -71.049292,
            "alt": 35,
            "azimuth": 35.5,
            "vertTilt": 8.9,
            "beamWidth": 5.3,
            "vendor": "skyhook",
            "repeaterId": 1234
          },
     
           "expirationDate": "2023-03-17" 
           "ttl": 60 
       },
      ...
     ]
    }
    Copy to clipboard

**Parameters**

| Parameter | Value | Description |
| --- | --- | --- |
| `apExpirationDate` | – | The date on which all the APs in the request expire, unless<br>                                explicitly overridden on a per AP level. Unit is<br>                                    `DATE` and the format is<br>                                    `yyyy-mm-dd`. |
| `apTtl` | – | The number of days until all the APs in the request expire,<br>                                unless explicitly overridden on a per AP level. Unit is<br>                                    `days`. |
| `cellExpirationDate` | – | The date on which all the cell towers in the request expire,<br>                                unless explicitly overridden on a per cell tower level. Unit is<br>                                    `DATE` and the format is<br>                                    `yyyy-mm-dd`. |
| `cellTtl` | – | The number of days until all the cell towers in the request<br>                                expire, unless explicitly overridden on a per cell tower level. Unit<br>                                is `days`. |
| `expirationDate` | – | The date on which the individual beacons (APs or cell towers) in<br>                                the request expire. Unit is `DATE` and the format is<br>                                    `yyyy-mm-dd`. <br>This value overrides the<br>                                    expiration date or TTL of all APs and cell towers. |
| `ttl` | – | The number of days until the individual beacons (APs or cell<br>                                towers) in the request expire. Unit is `days`.<br>This<br>                                    value overrides the expiration date or TTL of all APs and cell<br>                                    towers. |

Last Published: Jul 03, 2026

[Previous Topic
TPS user beacon API headers and authentication](https://docs.qualcomm.com/bundle/publicresource/80-42223-1/topics/user_beacon_api_headers_auth.md) [Next Topic
Sample TPS user beacon API request](https://docs.qualcomm.com/bundle/publicresource/80-42223-1/topics/sample_user_beacon_api_request.md)