Hide

The Google Maps Geolocation API

Overview

The Google Maps 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.

Identifying your application to Google

Your application must identify itself every time it sends a request to the Google Geolocation API for Business, by including an API key with each request. The API key is included as the value of a key parameter in the request URI:

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

Finding your API key

Usage limits

You can view and track your quota usage in the Quotas section of the Google Developers Console.

If you have purchased a Geolocation API for Business license:
Your Google Maps Geolocation API quota is assigned to you according to your Google Maps API for Work agreement. The Geolocation API is not included by default as a Google Maps API for Work product - if you haven't already added it to your license, please contact sales.

If you have not purchased a Geolocation API for Business license:
If you have set up billing in your API console account, you can use up to:
  • 100 queries per 24 hours.
  • 1 query per second, per user. This value can be changed in the Quotas section of the API Console.
See Finding your API key for more information. This shows up in the APIs console as billable quota, rather than Courtesy quota, but is billed at a price of $0 per query.

Logo and map requirements

If your application displays Geolocation API data on a map, that map must be provided by Google.

If your application displays Geolocation API data on a page or view that does not also display a Google Map, you must show a 'Powered by Google' logo with that data. For example, if your application displays a list of locations on one tab, and a Google Map with those locations on another tab, the first tab must show the 'Powered by Google' logo.

The following zip file contains the 'Powered by Google' logo in the correct sizes for desktop, Android and iOS applications. You may not resize or modify these logos in any way.

**Download:** powered-by-google.zip

Geolocation requests

Geolocation requests are sent using POST to the following URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=API_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 are lte, gsm, cdma, and wcdma. 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. Note that the IP address in the request header may not be the IP of the device. Defaults to true. Set considerIP to false 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.
{
  "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.

  • cellId: 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 WCDMAnetworks. 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, the cellId represents a current measurement.
  • signalStrength: Radio signal strength measured in dBm.
  • timingAdvance: The timing advance value.

An example GSM cell tower object is below.

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

An example WCDMA cell tower object is below.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

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. Separators must be : (colon) and hex digits must use uppercase.
  • 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.

{
  "macAddress": "01:23:45:67:89:AB",
  "signalStrength": -65,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 40
}

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 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": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

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 (the reason) and a short description (the message).

For example, sending invalid JSON will return the following error:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse 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've exceeded the requests per second per user limit that you configured in the APIs console. 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.
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

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

{
 "homeMobileCountryCode": 310,
 "homeMobileNetworkCode": 260,
 "radioType": "gsm",
 "carrier": "T-Mobile",
 "cellTowers": [
  {
   "cellId": 39627456,
   "locationAreaCode": 40495,
   "mobileCountryCode": 310,
   "mobileNetworkCode": 260,
   "age": 0,
   "signalStrength": -95
  }
 ],
 "wifiAccessPoints": [
  {
   "macAddress": "01:23:45:67:89:AB",
   "signalStrength": 8,
   "age": 0,
   "signalToNoiseRatio": -65,
   "channel": 8
  },
  {
   "macAddress": "01:23:45:67:89:AC",
   "signalStrength": 4,
   "age": 0
  }
 ]
}

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

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

(See Identifying your application to Google if you don't have an API key.)

For additional testing, you can gather information from your Android device using Network Info II (for cell tower info) and WiEye for WiFi access points.

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.

Send feedback about...

Google Maps Geolocation API