Geolocation request and response

Geolocation requests

Geolocation requests are sent using POST to the following URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

You must specify a key in your request, included as the value of a key parameter. A key is your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key.

Request body

The request body must be formatted as JSON. If the request body is not included, the results are returned based on the IP address of request location. The following fields are supported, and all fields are optional, unless otherwise stated:

Field JSON type Description Notes
homeMobileCountryCode number (uint32) The mobile country code (MCC) for the device's home network. Supported for radioType gsm (default), wcdma, lte and nr; not used for cdma.
Valid range: 0–999.
homeMobileNetworkCode number (uint32) The Mobile Network Code for the device's home network. This is the MNC for GSM, WCDMA, LTE and NR.
CDMA uses the System ID (SID)
Valid range for MNC: 0–999.
Valid range for SID: 0–32767.
radioType string The mobile radio type. Supported values are gsm, cdma, wcdma, lte and nr. While this field is optional, it should always be included if the radio type is known by the client.
If the field is omitted, Geolocation API default to gsm, which will result in invalid or zero results if the assumed radio type is incorrect.
carrier string The carrier name.
considerIp boolean Specifies whether to fall back to IP geolocation if WiFi and cell tower signals are missing, empty, or not sufficient to estimate device location. Defaults to true. Set considerIp to false to prevent fall back.
cellTowers array An array of cell tower objects. See the Cell Tower Objects section below.
wifiAccessPoints array An array of WiFi access point objects. See the WiFi Access Point Objects section below.

An example Geolocation API request body is shown below.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Cell tower objects

The request body's cellTowers array contains zero or more cell tower objects.

Field JSON type Description Notes
cellId number (uint32) Unique identifier of the cell. Required for radioType gsm (default), cdma, wcdma and lte; rejected for nr.
See the Calculating cellId section below, which also lists the valid value ranges for each radio type.
newRadioCellId number (uint64) Unique identifier of the NR (5G) cell. Required for radioType nr; rejected for other types.
See the Calculating newRadioCellId section below, which also lists the valid value range for the field.
locationAreaCode number (uint32) The Location Area Code (LAC) for GSM and WCDMA networks.
The Network ID (NID) for CDMA networks.
The Tracking Area Code (TAC) for LTE and NR networks.
Required for radioType gsm (default) and cdma, optional for other values.
Valid range with gsm, cdma, wcdma and lte: 0–65535.
Valid range with nr: 0–16777215.
mobileCountryCode number (uint32) The cell tower's Mobile Country Code (MCC). Required for radioType gsm (default), wcdma, lte and nr; not used for cdma.
Valid range: 0–999.
mobileNetworkCode number (uint32) The cell tower's Mobile Network Code. This is the MNC for GSM, WCDMA, LTE and NR.
CDMA uses the System ID (SID).
Required.
Valid range for MNC: 0–999.
Valid range for SID: 0–32767.

The following optional fields are not used, but may be included if values are available.

Field JSON type Description Notes
age number (uint32) The number of milliseconds since this cell was primary. If age is 0, the cellId or newRadioCellId represents a current measurement.
signalStrength number (double) Radio signal strength measured in dBm.
timingAdvance number (double) The timing advance value.

Calculating cellId

Radio types prior to NR (5G) use the 32-bit cellId field for passing the network cell ID to Geolocation API.

  • GSM (2G) networks use the 16-bit Cell ID (CID) as is. Valid range: 0–65535.
  • CDMA (2G) networks use the 16-bit Base Station ID (BID) as is. Valid range: 0–65535.
  • WCDMA (3G) networks use the UTRAN/GERAN Cell Identity (UC-ID), which is a 28-bit integer value concatenating the 12-bit Radio Network Controller Identifier (RNC-ID) and 16-bit Cell ID (CID).
    Formula: rnc_id << 16 | cid.
    Valid range: 0–268435455.
    Note: Specifying only the 16-bit Cell ID value in WCDMA networks results in incorrect or zero results.
  • LTE (4G) networks use the E-UTRAN Cell Identity (ECI), which is a 28-bit integer value concatenating the 20-bit E-UTRAN Node B Identifier (eNBId) and the 8-bit Cell ID (CID).
    Formula: enb_id << 8 | cid.
    Valid range: 0–268435455.
    Note: Specifying only the 8-bit Cell ID value in LTE networks results in incorrect or zero results.

Placing values outside these ranges in the API request may result in undefined behavior. The API, at Google's discretion, may truncate the number so it fits in the documented range, infer a correction to the radioType, or return a NOT_FOUND result without any indicator in the response.

An example LTE cell tower object is below.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Calculating newRadioCellId

Newer networks, whose cell IDs are longer than 32 bits use the 64-bit newRadioCellId field for passing the network cell ID to Geolocation API.

  • NR (5G) networks use the 36-bit New Radio Cell Identity (NCI) as is.
    Valid range: 0–68719476735.

An example NR cell tower object is below.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

WiFi access point objects

The request body's wifiAccessPoints array must contain two or more WiFi access point objects representing physically distinct access point devices. macAddress is required; all other fields are optional.

Field JSON type Description Notes
macAddress string The MAC address of the WiFi node. It's typically called a BSS, BSSID or MAC address. Required.Colon-separated (:) hexadecimal string.
Only universally-administered MAC addresses can be located via the API. Other MAC addresses are silently dropped and may lead to an API request becoming effectively empty. For details, see Dropping useless Wifi access points.
signalStrength number (double) The current signal strength measured in dBm. For WiFi access points, dBm values are typically -35 or lower and range from -128 to -10 dBm. Be sure to include the minus sign.
age number (uint32) The number of milliseconds since this access point was detected.
channel number (uint32) The channel over which the client is communicating with the access point.
signalToNoiseRatio number (double) The current signal to noise ratio measured in dB.

An example WiFi access point object is shown below.

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Sample requests

If you'd like to try the Geolocation API with sample data, save the following JSON to a file:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

You can then use cURL to make your request from the command line:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

The response for the preceding MAC addresses looks like this:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Dropping unused WiFi access points

Removing WiFi access point objects with macAddresses that are locally-administered can improve the success rate of Geolocation API calls that use WiFi as input. If, after filtering, it can be determined that a Geolocation API call would not succeed, mitigations such as using older location signals or WiFi APs with weaker signals can be used. This approach is a tradeoff between your application's need for a location estimate and its precision and recall requirements. The following filtering techniques demonstrate how to filter the inputs, but do not show the mitigations that you may, as the application engineer, choose to apply.

Locally administered MAC addresses are not useful location signals for the API and are silently dropped from requests. You can remove such MAC addresses by ensuring that the second least-significant bit of the macAddress's most-significant byte is 0, e.g. the 1 bit represented by the 2 in 02:00:00:00:00:00. The broadcast MAC address (FF:FF:FF:FF:FF:FF) is an example of a MAC address that would be usefully excluded by this filter.

The range of MAC addresses between 00:00:5E:00:00:00 and 00:00:5E:FF:FF:FF are reserved for IANA and often used for network management and multicast functions which precludes their use as a location signal. You should also remove these MAC addresses from inputs to the API.

For example, usable MAC addresses for Geolocation can be gathered from an array of macAddress strings named macs:

Java
String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16))
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    
Python
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    
JavaScript
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

Using this filter results in only 1c:34:56:78:9a:bc remaining in the list. Because this list has fewer than 2 WiFi MAC addresses, the request would not be successful and an HTTP 404 (notFound) response would be returned.

Geolocation responses

A successful geolocation request returns a JSON-formatted response defining a location and radius.

  • location: The user's estimated latitude and longitude coordinates, in degrees. Contains one lat and one lng subfield.
  • accuracy: The accuracy of the estimated location, in meters. This represents the radius of a circle around the given location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}