Google Maps & Earth Enterprise Support Team
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 Google Maps API for Work FAQ.
This article is intended for Google Maps API for Work customers who reach these limits and may need to optimize applications to use the web services more efficiently.
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.
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
status code as a
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
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
- From the Elevation API when more than 512 points per request are provided.
- From the Distance Matrix API when more than 625 elements per request are provided.
Applications should ensure these limits are not reached before sending requests.
HTTP 403 response
Requests to the web services may also receive a
(Forbidden) error. In most cases, this is due to an invalid URL signature.
To verify this, remove the
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 Google Maps API for Work 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
parameter, or vice versa.
The above problems can be address by combining two approaches:
- Lowering usage, by optimizing applications to use the web services more efficiently.
- Increasing usage limits, when possible, by purchasing additional allowance for your Google Maps API for Work license.
This article will focus on ways of optimizing applications to use the web services more efficiently.
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.
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 Google Maps API for Work license
If you have a Google Maps API for Work license, make sure your requests include your client ID correctly.
Google Maps API for Work customers are provided with
higher usage limits for the Google Maps API Web Services than
free API users. In order to benefit from this, your applications must
client= parameter correctly as described in the
chapter of this guide.
Applications that fail to use a Google Maps API for Work client ID correctly will not be treated as Business, will not benefit from Business-only features and allowances, will not be covered by the Google Maps API for Work 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.
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
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.
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
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.
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
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 Google Maps API for Work 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 Google Maps API for Work license. In that case, please contact your Google Maps API for Work Account Manager to discuss available options.