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.
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
macAddress
es 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
:
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")));
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')]
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
}