Google Maps API for Business

Usage Limits for Google Maps API Web Services

Google Maps & Earth Enterprise Support Team
December 2011

Use of the Google Maps API Web Services is subject to specific limits on the amount of requests per 24 hour period. Requests sent in excess of these limits will receive an error message.

Usage limits are documented in the Maps API for Business FAQ.

This article is intended for Maps API for Business customers who reach these limits and may need to optimize applications to use the web services more efficiently.

Contents

  1. Basics
  2. Problems
    1. Usage limits exceeded
    2. HTTP 403 response
  3. Solutions
    1. Sanity checks
      1. Validate your use case
      2. Use a Maps API for Business license
    2. How to optimize
      1. Cache results
      2. Throttle requests
      3. Handle backlog
    3. When optimizing is not enough

Basics

The Google Maps API family provides web services as an interface for requesting Maps API data for use within your applications. These services may only be used in conjunction with a Google map; using data from these services without displaying them on a Google map is prohibited. For complete details, consult the Maps API Terms of Service License Restrictions.

There are two types of quotas that limit the usage of Google Maps API Web Services: long term (per day quota) and short term (request rate quota). If you exceed the usage limits or otherwise abuse the service, the web service will return a specific error message. If you continue to exceed limits, your access to the web service may be blocked. It is also possible to receive 403 Forbidden responses.

Note: different limits apply to client-side APIs. Flash and JavaScript Maps APIs are rate limited per map session, so that requests are distributed across users. This makes the browser based usage scalable as your user count grows. For information how to choose between server-side web services and their client-side equivalent refer to the Geocoding Strategies article.

Problems

You can exceed the Google Maps API Web Services usage limits by:

  • Sending too many requests per day.
  • Sending requests too fast, i.e. too many requests per second.
  • Sending requests too fast for too long or otherwise abusing the web service.
  • Exceeding other usage limits, e.g. points per request in the Elevation API.

Usage limits exceeded

If you exceed the usage limits you will get an OVER_QUERY_LIMIT status code as a response.

This means that the web service will stop providing normal responses and switch to returning only status code OVER_QUERY_LIMIT until more usage is allowed again. This can happen:

  • Within a few seconds, if the error was received because your application sent too many requests per second.
  • Some time in the next 24 hours, if the error was received because your application sent too many requests per day. The time of day at which the daily quota for a service is reset varies between customers and for each API, and can change over time.

Upon receiving a response with status code OVER_QUERY_LIMIT, your application should determine which usage limit has been exceeded. This can be done by pausing for 2 seconds and resending the same request. If status code is still OVER_QUERY_LIMIT, your application is sending too many requests per day. Otherwise, your application is sending too many requests per second.

The screencast below provides a step-by-step explanation of proper request throttling and error handling, which is applicable to all web services:

Here is an example implementation in Python:

url = "MAPS_API_WEBSERVICE_URL"
attempts = 0
success = False

while success != True and attempts < 3:
  raw_result = urllib.urlopen(url).read()
  attempts += 1
  # The GetStatus function parses the answer and returns the status code
  # This function is out of the scope of this example (you can use a SDK).
  status = GetStatus(raw_result)
  if status == "OVER_QUERY_LIMIT":
    time.sleep(2)
    # retry
    continue
  success = True

if attempts == 3:
  # send an alert as this means that the daily limit has been reached
  print "Daily limit has been reached"

Note: It is also possible to get the OVER_QUERY_LIMIT error:

Applications should ensure these limits are not reached before sending requests.

HTTP 403 response

Requests to the web services may also receive a HTTP 403 (Forbidden) error. In most cases, this is due to an invalid URL signature. To verify this, remove the client and signature parameters and try again:

  • If the response is HTTP 200 (OK), the signature was the problem.
    This is not related to usage limits; see Troubleshooting authentication issues in the Web Services chapter of the Maps API for Business documentation for details.
  • If the response is still a HTTP 403 (Forbidden) error, the signature was not necessarily the problem, it may be related to usage limits instead.
    This typically means your access to the web service has been blocked on the grounds that your application has been exceeding usage limits for too long or otherwise abused the web service. Please contact Google Enterprise Support if you encounter this issue.

Requests to all web services require URL signatures. Requests will also be rejected with a HTTP 403 (Forbidden) error when including the client parameter but missing the signature parameter, or vice versa.

Solutions

The above problems can be address by combining two approaches:

  1. Lowering usage, by optimizing applications to use the web services more efficiently.
  2. Increasing usage limits, when possible, by purchasing additional allowance for your Maps API for Business license.

This article will focus on ways of optimizing applications to use the web services more efficiently.

Sanity checks

Before jumping into details on how to use a web service more efficiently, it's worth taking the time to check that the right service and license are used.

Validate your use case

Google Maps API Web Services are best used for applications that lack real-time input from end users or where a web browser is not available. This usually happens when you get a dataset that is independent of user input. For instance, if you have a database with a fixed set of addresses that need geocoding, like a set of properties offered for sale on a real estate web site, or a set of store locations.

When using the Google Maps API Web Services, all requests count against the (daily and per-second) quota of your client ID. This quota is global to each client ID, regardless of how many IP addresses the requests are sent from.

Using client-side Maps API services (JavaScript and Flash) in the browser is rate limited per map session. That means that requests are distributed across all your users and scale as the number of users grows. Therefore, client-side APIs should be always preferred and used whenever possible. They are the best match if you are collecting addresses from users that need to be geocoded in real time, like performing a search for stores near the user's home address.

For a more detailed discussion on this topic, see the Geocoding Strategies article. Although specific to geocoding, this article applies to all web services and explains when you should use server-side web services and when you should use their client-side equivalents.

Use a Maps API for Business license

If you have a Maps API for Business license, make sure your requests include your client ID correctly.

Maps API for Business customers are provided with higher usage limits for the Google Maps API Web Services than those for free API users. In order to benefit from this, your applications must set the client= parameter correctly as described in the Web Services chapter of this guide.

Applications that fail to use a Maps API for Business client ID correctly will not be treated as Business, will not benefit from Business-only features and allowances, will not be covered by the Maps API for Business SLA, will not be entitled to technical support and will be subject to the regular Maps API Terms of Service License Restrictions.

How to optimize

Using the web services more efficiently can be summarized in two major objectives: lower usage by sending requests only when really necessary and spread usage evenly to keep it under the limits.

Cache results

Section 10.1.3 of the Maps API Terms of Service establishes that you may store limited amounts of Content for the purpose of improving the performance of your Maps API Implementation if you do so temporarily, securely, and in a manner that does not permit use of the Content outside of the Service.

This means you may temporarily cache Web Service responses to avoid sending duplicate requests over short time spans. Responses from web services always include the Cache-Control HTTP header to indicate how long the result can be cached for, currently 24 hours:

Cache-Control: public, max-age=86400

This header should always be honored. Caching can be implemented using web proxies, which should do this out of the box or using your own implementation. It’s worth pointing out that some HTTP client libraries also cache HTTP responses.

To increase cache hit rates, LatLng coordinates should be normalized by rounding to 6 decimal places, which provides a precision of around 11 centimeters around the equator. Results from web services will not differ by adding more decimals, while doing so would decrease cache hit rates.

Throttle requests

Applications should throttle requests to avoid exceeding usage limits, bearing in mind these apply to each client ID regardless of how many IP addresses the requests are sent from.

You can throttle requests by putting them through a queue that keeps track of when are requests sent. With a rate limit or 10 QPS (queries per second), on sending the 11th request your application should check the timestamp of the first request and wait until 1 second has passed. The same should be applied to daily limits.

Even if throttling is implemented correctly applications should watch out for responses with status code OVER_QUERY_LIMIT. If such response is received, use the pause-and-retry mechanism explained in the Usage limits exceeded section above to detect which limit has been exceeded.

Handle backlog

With throttling correctly implemented, requests to the web services would not be sent in excess of usage limits. However, applications may receive input in larger volumes or at a higher speeds than those allowed by web services usage limits. This may result in the throttling queues growing significantly, creating a backlog of pending requests.

Your applications may hit daily usage limits while processing a large backlog. If throttling is correctly implemented for the daily limits, applications would stop sending requests; otherwise sending additional requests would encounter responses with status code OVER_QUERY_LIMIT. In both cases, the backlog would not decrease.

If the average volume of requests over a whole day or week is still under the usage limits, your applications should be able to get through the backlog during periods of lower input flow. Otherwise, you may need to increase the daily allowance for your Maps API for Business license (see next section).

When optimizing is not enough

If you have all the above optimizations already implemented and your backlog of requests grows consistently, either on a daily basis or at all times through the day, you may actually need to increase the per-day or per-second usage limits for your Maps API for Business license. In that case, please contact your Maps API for Business Account Manager to discuss available options.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.