Find local businesses, view maps and get driving directions in Google Maps.
New Users: Before you can start using the Google Maps Platform APIs and SDKs, you must sign up and create a billing account.To learn more, see Get Started with Google Maps Platform.Introduction
The Geolocation API returns a location and accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect. This document describes the protocol used to send this data to the server and to return a response to the client.
Communication is done over HTTPS using POST. Both request and response are formatted as JSON, and the content type of both is
application/json
.Before you begin
Before you start developing with the Geolocation API,review the authenticationrequirements (you need an API key) and theAPI usage and billing information (you need to enable billing on your project).
Geolocation requests
Geolocation requests are sent using POST to the following URL:
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. The following fields are supported, and all fields are optional:
homeMobileCountryCode
: The mobile country code (MCC) for the device's home network.homeMobileNetworkCode
: The mobile network code (MNC) for the device's home network.radioType
: The mobile radio type. Supported values arelte
,gsm
,cdma
, andwcdma
. While this field is optional, it should be included if a value is available, for more accurate results.carrier
: The carrier name.considerIp
: Specifies whether to fall back to IP geolocation if wifi and cell tower signals are not available. Defaults totrue
. SetconsiderIp
tofalse
to disable fall back.cellTowers
: An array of cell tower objects. See the Cell Tower Objects section below.wifiAccessPoints
: An array of WiFi access point objects. See the WiFi Access Point Objects section below.
Cell tower objects
The request body's
cellTowers
array contains zero or more cell tower objects.cellId
(required): Unique identifier of the cell. On GSM, this is the Cell ID (CID); CDMA networks use the Base Station ID (BID). WCDMA networks use the UTRAN/GERAN Cell Identity (UC-Id), which is a 32-bit value concatenating the Radio Network Controller (RNC) and Cell ID. Specifying only the 16-bit Cell ID value in WCDMA networks may return inaccurate results.locationAreaCode
(required): The Location Area Code (LAC) for GSM and WCDMA networks. The Network ID (NID) for CDMA networks.mobileCountryCode
(required): The cell tower's Mobile Country Code (MCC).mobileNetworkCode
(required): The cell tower's Mobile Network Code. This is the MNC for GSM and WCDMA; CDMA uses the System ID (SID).
The following optional fields are not currently used, but may be included if values are available.
age
: The number of milliseconds since this cell was primary. If age is 0, thecellId
represents a current measurement.signalStrength
: Radio signal strength measured in dBm.timingAdvance
: The timing advance value.
An example GSM cell tower object is below.
An example WCDMA cell tower object is below.
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.macAddress
: (required) The MAC address of the WiFi node. It's typically called a BSS, BSSID or MAC address. Separators must be:
(colon).signalStrength
: The current signal strength measured in dBm.age
: The number of milliseconds since this access point was detected.channel
: The channel over which the client is communicating with the access point.signalToNoiseRatio
: The current signal to noise ratio measured in dB.
An example WiFi access point object is shown below.
Geolocation responses
A successful geolocation request will return a JSON-formatted response defining a location and radius.
location
: The user’s estimated latitude and longitude, 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
.
Errors
In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status.
The response contains an object with a single
error
object with the following keys:code
: This is the same as the HTTP status of the response.message
: A short description of the error.errors
: A list of errors which occurred. Each error contains an identifier for the type of error (thereason
) and a short description (themessage
).
For example, sending invalid JSON will return the following error:
Possible errors include:
Reason | Domain | HTTP Status Code | Description |
---|---|---|---|
dailyLimitExceeded | usageLimits | 403 | You have exceeded your daily limit. |
keyInvalid | usageLimits | 400 | Your API key is not valid for the Geolocation API. Please ensure that you've included the entire key, and that you've either purchased the API or have enabled billing and activated the API to obtain the free quota. |
userRateLimitExceeded | usageLimits | 403 | You have exceeded the request limit that you configured in the Google Cloud Platform Console. This limit is typically set as requests per day, requests per 100 seconds, and requests per 100 seconds per user. This limit should be configured to prevent a single or small group of users from exhausting your daily quota, while still allowing reasonable access to all users. See Capping API Usage to configure these limits. |
notFound | geolocation | 404 | The request was valid, but no results were returned. |
parseError | global | 400 | The request body is not valid JSON. Refer to the Request Body section for details on each field. |
Sample requests
Note: Mac addresses can change over time. For that reason, the examples on this page may result in an error message from the API.If you'd like to try the Geolocation API with sample data, save the following JSON to a file:
You can then use cURL to make your request from the command line:
The response for the above Mac addresses looks like this:
(See Get a Key if you don't have an API key.)
For additional testing, you can gather information from your Android device using the Places SDK for Android and the Android Location APIs, and from your iOS device using the Places SDK for iOS.
Frequently asked questions
Why am I getting a very large
accuracy
radius in my Geolocation response?If your Geolocation response shows a very high value in the
accuracy
field, the service may be geolocating based on the request IP, instead of WiFi points or cell towers. This can happen if no cell towers or access points are valid or recognized.To confirm that this is the issue, set
considerIp
to false
in your request. If the response is a 404
, you've confirmed that your wifiAccessPoints
and cellTowers
objects could not be geolocated.Using Google Maps on my mobile phone
Want to use GPS navigation in Google Maps? It's easy, but remember you need to set up your mobile phone for internet and turn on GPS before you can use this function.
The following steps describe how you:
Find a destination
Use zoom
Save a destination as a favourite
Plan a route to a destination
Start GPS navigation
Exit GPS navigation
Find a destination
Use zoom
Save a destination as a favourite
Plan a route to a destination
Start GPS navigation
Exit GPS navigation
Tap Google.
Key in the required destination.
Results matching what you key in are displayed.
Key in the required destination.
Results matching what you key in are displayed.
Drag two fingers together or apart to zoom in or out.
Tap the star until the destination has been saved as a favourite.
Tap the start navigation icon.
The navigation window with information about your route is displayed.
The navigation window with information about your route is displayed.
The travel information at the bottom of the display shows your estimated time of arrival and distance to destination.
Follow the verbal instructions or the instructions on the display to go to the selected destination.
Follow the verbal instructions or the instructions on the display to go to the selected destination.
Tap the return icon the necessary number of times to exit GPS navigation.