This page is only for customers with a previous Maps APIs for Work or Maps API for Business license. This page is not applicable to customers with the new Google Maps APIs Premium Plan, which became available in January 2016.
December 2011
Use of the Google Maps Platform 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 APIs for Work FAQ for Previous Licenses.
This article is intended for Google Maps APIs for Work customers who reach these limits and may need to optimize applications to use the web services more efficiently.
Basics
The Google Maps provides web services as an interface for requesting Google maps 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 License Restrictions in the Google Maps Platform Terms of Service.
There are two types of quotas that limit the usage of Google Maps Platform 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. Maps JavaScript API 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 document.
Problems
You can exceed the Google Maps Platform 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.
- Within the next 24 hours, if the error was received because your application sent too many requests per day. The daily quotas are reset at midnight, Pacific Time.
This screencast provides a step-by-step explanation of proper request throttling and error handling, which is applicable to all web services.
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.
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:
- 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 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 Google Maps APIs 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 access the Google Cloud Support Portal if you encounter this issue. Contact information is also available on the Support and resources page.
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:
- 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 APIs for Work 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 Platform 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 Platform 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 JavaScript API services 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 are 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 document. Although specific to geocoding, the recommendations in this document apply to all web services, explaining when you should use server-side web services and when you should use their client-side equivalents.
Use a Google Maps APIs for Work license
If you have a Google Maps APIs for Work license, make sure your requests include your client ID correctly.
Google Maps APIs for Work customers are provided with
higher usage limits for the Google Maps Platform 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 Google Maps APIs 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 APIs for Work SLA, will not be entitled to technical support and will be subject to the regular License Restrictions in the Google Maps Platform Terms of Service.
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 3.2.4 of the Google Maps Platform Terms of Service establishes that caching is permitted for certain Services, as described in the Google Maps Platform Service Specific Terms. Specifically, you may store limited amounts of Content solely for the purpose of improving the performance of your Google Maps Platform Implementation due to network latency (and not for the purpose of preventing Google from accurately tracking usage), and only if such storage: is temporary (and in no event more than 30 calendar days); is secure; does not manipulate or aggregate any part of the Content or Service; and, does not modify attribution in any way.
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 of 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 Google Maps APIs 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 APIs for Work license. In that case, please contact your Google Maps APIs for Work Account Manager to discuss available options.