Optimizing Quota Usage When Geocoding

  • Geocoding transforms addresses into geographic coordinates for map placement, offered through client-side (browser-based) and server-side (HTTP) approaches by the Google Maps Platform.

  • Client-side geocoding, ideal for user-input addresses, provides a faster experience and leverages user context for improved accuracy.

  • Server-side geocoding is suitable for geocoding pre-defined address datasets or as a fallback when client-side geocoding fails.

  • Google Maps Platform's geocoding service is rate limited to 3,000 queries per minute, and each request is billed individually.

  • Consider caching, request staggering, or inexact repeating alarms to manage costs and avoid rate limits, especially in high-frequency scenarios.

Geocoding is the process of converting addresses ("1600 Amphitheatre Parkway, Mountain View, CA") to geographic coordinates (37.423021, -122.083739), which you can use to place markers or position the map. The Google Maps Platform APIs provide two approaches to geocoding:

  • Client-side geocoding, which is executed in the browser, generally in response to user action. The Maps JavaScript API provides classes that make the requests for you. This approach is described in the Maps JavaScript API documentation.
  • HTTP server-side geocoding, which allows your server to directly query Google's servers for geocodes. The Geocoding API is the web service that provides this functionality. Typically, you integrate this service with other code that is running server-side. Server-side geocoding is described in the Geocoding API documentation.

Examples of client-side and server-side geocoding

Here is a sample of client-side geocoding which takes an address, geocodes it, moves the center of the map to that location, and adds a map marker there:

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

For more examples, see the Maps JavaScript API documentation.

Here is an example using Python to do a server-side geocoding request in Geocoding API v4:

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

This produces a JSON object with the following content:

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

For more examples, see the Geocoding API v4 overview and the Geocode an address guide.

Quota and cost considerations

Geocoding costs, quotas, and rate limits drive the strategies outlined in this document.

Cost

Quota-per-day (QPD) limits aren't in use for geocoding requests. Instead, each geocoding request, whether client-side through the browser or server-side through the Geocoding API web service, is billed at a per-request price. To manage your cost of use, consider managing your usage limits and quotas.

Rate limits

The geocoding service is rate limited to 3,000 QPM (queries per minute), calculated as the sum of client-side and server-side queries.

When running client-side geocoding requests at periodic intervals, such as in a mobile app, your requests may return errors if all of your users are making requests at the same time (for example, all at the same second of every minute). To avoid this, consider one of the following:

  • Introduce random intervals to your requests (jitter). Ensure requests are random across your entire user base.
  • If developing for Android, use an inexact repeating alarm.
  • If developing for Android, select an appropriate location strategy.

Caching

See Geocoding API Policies about caching.

Server-side versus client-side architecture in v4

The Geocoding API v4 (including SearchDestinations, GeocodeAddress, GeocodeLocation, and GeocodePlace) is designed as a server-to-server API. Calling v4 endpoints from your backend server offers critical advantages:

  • Hyperlocal arrival intelligence: The SearchDestinations method (POST /v4/geocode/destinations) is available exclusively using server-side REST or gRPC requests and returns building entrances, routable navigation points, building outlines, and nearby landmarks that are not available in client-side browser geocoders.
  • Enhanced API security: Server-side calls protect your API keys and OAuth tokens from exposure in client browsers. See API security.
  • Response field masks: Server-side v4 endpoints support field masks, allowing you to request only the fields your application requires to minimize payload size and latency.

When to use client-side browser lookup

For interactive browser applications responding to live keystrokes, consider combining client-side Place Autocomplete (to disambiguate user input and obtain a Place ID) with a backend call to SearchDestinations or GeocodePlace to retrieve hyperlocal details or coordinates securely.