Page Summary

outlined_flag

• The Google Geolocation API returns a location and accuracy radius based on cell tower and WiFi access point data sent in a POST request.

• Request bodies are formatted in JSON and should includecellTowers andwifiAccessPoints arrays with relevant signal data for optimal results.

• Locally administered MAC addresses and reserved IANA ranges for WiFi access points should be filtered out to improve the success rate of API calls.

• cellId andnewRadioCellId fields are used to identify cell towers with specific calculation methods based on radio type.

• Successful responses provide latitude and longitude coordinates within alocation object, along with anaccuracy value representing the radius of uncertainty in meters.

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 akey parameter. Akey is your application's API key. This key identifies your application for purposes of quota management. Learn how toget a key.

Request body

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

An example Geolocation API request body is shown below.

{"homeMobileCountryCode":310,"homeMobileNetworkCode":410,"radioType":"lte","carrier":"Vodafone","considerIp":true,"cellTowers":[// See theCell Tower Objects section below.],"wifiAccessPoints":[// See theWiFi Access Point Objects section below.]}

Cell tower objects

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

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

CalculatingcellId

Radio types prior to NR (5G) use the 32-bitcellId 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 theradioType, or return aNOT_FOUND result without any indicator in the response.

An example LTE cell tower object, which is part of therequest body, is below.

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

The response for the preceding request looks like this:

{"location":{"lat":37.7801129,"lng":-122.4168229},"accuracy":180.052}

CalculatingnewRadioCellId

Newer networks, whose cell IDs are longer than 32 bits use the 64-bitnewRadioCellId 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, which is part of therequest body, is below.

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

The response to the preceding request looks like this:

{"location":{"lat":37.7646157,"lng":-122.4127361},"accuracy":1458.5570522410717}

WiFi access point objects

The request body'swifiAccessPoints array must contain two or more WiFi access point objects representingphysically distinct stationary access point devices. ThemacAddress field is required. All other fields are optional. The service ignores access points that move, such as those in airplanes and trains.

An example WiFi access point object, which is part of therequest body, isshown below.

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

The response for the preceding request looks like this:

{"location":{"lat":37.7801129,"lng":-122.4168229},"accuracy":180.052}

Sample requests

{"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 usecurl 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 withmacAddresses that arelocally-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 wouldn't 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 don't 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 themacAddress's most-significant byte is0, e.g. the1 bit represented by the2 in02: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 between00:00:5E:00:00:00 and00:00:5E:FF:FF:FF arereserved 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 ofmacAddress strings namedmacs:

String[]macs={"12:34:56:78:9a:bc","1c:34:56:78:9a:bc","00:00:5e:00:00:01"};ArrayList<String>_macs=newArrayList<>(Arrays.asList(macs));_macs.removeIf(m->!(0==(2 &Integer.parseInt(m.substring(1,2),16))                      &&!m.substring(0,8).toUpperCase().equals("00:00:5E")));

macs=['12:34:56:78:9a:bc','1c:34:56:78:9a:bc','00:00:5e:00:00:01']macs=[mforminmacsif(0==(2 &int(m[1],16))andm[:8].upper()!='00:00:5E')]

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 only1c:34:56:78:9a:bcremaining in the list. Because this list hasfewer than 2 WiFi MAC addresses, therequest wouldn't 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 onelat and onelng subfield.
• accuracy: The accuracy of the estimated location, in meters. This represents the radius of a circle around the givenlocation.

{"location":{"lat":37.421875199999995,"lng":-122.0851173},"accuracy":120}