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.
- Ensuring Your Team Has Access to the Necessary Resources
- Application Optimization
- Configure Firewall to Allow Access to the Google Maps Platform Services
- Loading the APIs Over SSL
- Using Client-side Maps APIs in Your SSL Domains
- Proper API Version Selection
- Optimize Page View Usage
- Client-side Vs. Server-side Design: Pick the One That's Right for Your Use Case
- Web Services Quota and Management
- Load testing
- Migrating from Free to Google Maps APIs for Work Implementations
Ensuring Your Team Has Access to the Necessary Resources
Receipt of the Google Maps APIs for Work Welcome Letter
Why it's important: Your welcome letter is your Google Maps APIs for Work starter kit and perhaps also your first aid kit. It contains critical bits of information such as your client ID and cryptographic key which are necessary to begin using the Google Maps Platform. It also contains all the information you need to contact the Google Cloud Support team should you experience any technical issues with any of the Google Maps Platform.
Have Access to and Use the Google Cloud Support Portal
Why it's important: The support portal gives you access to information such as usage reports, news feeds, and useful developer resources. More importantly, the support portal will allow you to file support cases with the Google Maps Platform Support team should you encounter any technical issues during development or launch. You can access the support portal at the following URL:
Prior to launch, please take the time to enable support portal access for all developers responsible for your application's maintenance. Should you experience technical issues, access to the support portal will serve the dual advantage of allowing members of your team to contact support and allowing our support team to contact the proper stakeholders in your organization. For example, the support team may need to contact your organization should we detect abnormal traffic or behavior that could end up breaking your application. Ensuring that we have the appropriate developers to contact could be the difference between an unexpected outage and preventing an outage. If you do not have access to the support portal, please request access here:
Subscribe to Relevant Notification Feeds
Why it's important: To ensure you stay abreast with developments and changes across the Google Maps Platform, we recommend subscribing to the relevant notification feeds. You should subscribe to the Google Geo Developers Blog as well as the relevant notify Google Groups for the APIs you are using, as described here:
Please take a moment now to subscribe to the notify groups for the APIs that you are using or plan to use. You may also subscribe to the following RSS feed:
to receive updates from the Google Maps Platform support teams.
Have the Support Hotline Handy
1-877-355-5787 for US customers, +1 404-978-9282 for Customers Outside the US
Why it's important: The hotline is your way to phone Google Cloud Support Portal. Please bookmark this page to find the latest and up-to-date support hotline number. Please note that while you are welcome to utilize the support hotline to report technical issues to our team, it is reserved for production down, service unusable cases only. Our priority levels are defined at:
Configure Firewall to Allow Access to the Google Maps Platform Services
Why it's important: Google Maps Platform services use a variety
of domains, some of which do not belong to the
domain. If you are behind a restrictive firewall, it is important to allow access to the
domains used by each Maps API service. If your firewall doesn't allow access to these domains,
API requests will fail, which can break your applications. You can find a complete list of
domains used by the Maps APIs in the Support Portal:
- Log in to the
Google Cloud Support Portal.
The Support Portal is available only to customers with the Google Maps APIs Premium Plan or a previous Google Maps APIs for Work or Google Maps for Business license.
- Navigate to the Resources tab.
- Select List of domains used by the Google Maps Platform family.
- Allow your applications to access the listed domains.
We do not recommend managing firewall restrictions by IP address, as the IPs associated with these domains are not static.
Note: Google Maps Platform services use port 80 (http) and 443 (https) for inbound and outbound traffic. These services also require GET, POST, PUT, DELETE, and HEAD requests. Configure your firewall to allow traffic over these ports and to allow requests, depending on the API and use case.
Loading the APIs Over SSL
Why it's important: Applications that load the
Web service APIs,
or image APIs
over SSL should do so from
rather than the legacy hostname,
Using Client-side Maps APIs in Your SSL Domains
Why it's important: When using a
client-side API with an SSL domain, it's critical you have explicitly authorized your
HTTPS domains to ensure your requests are not rejected. Please note that authorizing
http://yourdomain.com does not automatically enable its SSL equivalent,
https://yourdomain.com. You can check your list
of authorized domains in the Google Cloud Support Portal
by selecting the Maps: Manage Client ID link from the navigation menu on the left.
To troubleshoot errors related to using the client-side APIs with an SSL domain, we encourage you
to first check whether any elements of your page are loaded over HTTP. Please also see our
Authorization for Google Maps APIs for Work Implementations article.
Proper API Version Selection
Why it's important: Before developing your application, it's important to be aware which versions of the APIs are deprecated. Choosing to develop against the non-deprecated versions of the APIs will save you development time and cost down the road once deprecated versions become unavailable.
It's also critical to understand the API's versioning scheme to avoid accidentally using an improper version of the API in your environment:
For example, it may be suitable to use the nightly (i.e., experimental) version of the API in your dev/test environment, but we strongly discourage using the nightly version in a production environment. Our SLA only applies to stable versions of the API, so you should only use stable versions in your production environment.
Optimize Page View Usage
Why it's important: If you don't always display a Google Map on your site, why pay for it? As a best practice for using your page views more efficiently, we suggest loading the Maps APIs asynchronously on those pages where you actually display a map. This will greatly reduce the number of purchased page views that your applications consume. Keep in mind that every time a page which loads the API is refreshed, it will incur an additional page view. As a result, we recommend when designing your application that your site which loads the API only initiates page refreshes when absolutely needed.
Client-side Vs. Server-side Design: Pick the One That's Right for Your Use Case
Why it's important: Choosing a client- or server-side approach is an architectural decision and is absolutely critical to the stability and scalability of your application. By and large, a server-side approach should be used for pre- and post- processing of records offline (i.e., outside of your application). Alternately, a client-side approach should be used for the portions of your applications which interact with your users (i.e., process user-submitted requests in real time).
Deploying a server-side approach where a client-side approach should be used instead is the leading cause for exceeding quotas and, hence, broken applications. We highly recommend consulting the Geocoding Strategies document before designing or launching applications that rely on server-side calls.
Web Services Quota and Management
Why it's important: By default, the web services quota
are set at a quota of 100,000 queries per 24 hours. For a more detailed quota
breakdown per API, please visit the
limits documentation. To confirm how much quota is available to your
client ID, please file a
support case. Before
launching your service, it is critical that you understand the different
quota related errors (e.g.
User Rate Limit Exceeded),
and set up the proper logic in your application to be able to respond to such
errors when you exceed your quota. Please start by reading the Usage
Limits for Google Maps Platform Web Services article.
Understanding and implementing these concepts will greatly reduce the
chances of your application exceeding its allowed quota, being blocked by
Google, and/or breaking.
Why it's important: Load testing against live Google services will lead to your application exceeding its allowed quota and being blocked by Google.
Google Maps Platform can serve very high volumes; in 2012, Santa Tracker served 1,600,000 requests per second. Therefore, there is no need to do load testing against Google services. Instead, load testing your application should ensure that your application is able to cope with high volumes of requests without exceeding your quotas for the Maps APIs. Example: if your quota for the Geocoding API is 20 QPS (queries per second), load testing your application should ensure that your application can handle 600 QPS without sending more than 20 QPS to the Geocoding API.
To safely achieve this, load testing should be done against a mock (fake) API — a service that can absorb high amounts of requests and reply to them with valid responses, without involving the Google Maps Platform. Thus you can load test your application without risking being blocked by the Google Maps Platform.
Please see this example of such a mock API, implemented as a small Google App Engine application: https://github.com/googlemaps/js-v2-samples/blob/gh-pages/mock_maps_apis/. You can upload this to your own App Engine application (after you register one at https://appengine.google.com/) and make your application send requests there instead of to maps.googleapis.com.
Default (free) App Engine quotas should generally
be enough to load test your application well beyond your quotas for the Maps APIs web services.
Please make sure your application sets the correct
User-Agent header to enable response compression. This is critical to
ensure efficient usage of bandwidth, which is particularly important for an App Engine
application serving a high volume of plain text (JSON/XML) responses.
Should you need higher quota for your App Engine application, you can also
enable billing, although this should rarely be necessary.
Migrating your APIs from a free to a Google Maps APIs for Work license
The Street View API and Maps Static API can be used either in a client-side or server side fashion, both incurring page views. As a result, these APIs require that you sign your requests using your cryptographic key and also that you authorize any domains utilizing these APIs. This ensures that your application is properly billed, in adherence with our ToS, supported, and covered by our SLA.
You can check your list of authorized domains in the Google Cloud Support Portal by selecting the Maps: Manage Client ID link from the navigation menu on the left.
For authorization issues, we recommend reviewing the Troubleshooting Authorization for Google Maps APIs for Work Implementations article before filing a case.
Integration of Your Client ID (eg.
Why it's important: One of the most important things you
can do for your application is to ensure you include
&client=gme-yourclientid' in your requests. Your unique
client ID can be found in your welcome letter which was issued to your
organization's primary contact(s). The client ID identifies your
requests as a Google Maps APIs for Work request. You must include your client
ID in your applications in order to benefit from any features specific to
Google Maps APIs for Work. Inclusion of your client ID is also necessary in
order to receive Technical Support and to ensure your application is under
Utilizing the Cryptographic Key (eg.
vNIXE0xscrmjlyV-12Nj_BvUPaw=) to Sign Web Services
Why it's important: Your private, cryptographic key is used to generate signatures which communicate to Google that your requests have come from a trusted source. Your cryptographic key can be found in your welcome letter which was issued to your organization's primary contact(s). As a Google Maps APIs for Work customer, our Web Services require that you sign your requests using your cryptographic key. This adds a layer of security on top of your request which will better safeguard the quota associated with your client ID.
Please note: the cryptographic key is used to generate signatures. It is not to be appended to your requests as a signature itself. Your cryptographic key is similar to an ATM pin number. It is used as a means of authentication in order to access your account and should never be openly shared with or visible to untrusted sources. Google Maps APIs for Work web services requests which are not properly signed will be rejected by our servers so it's critical your application properly signs request prior to launch (nb. v2 Geocoding API does not currently require signatures). Please see our documentation on URL signing:
Tracking Application Usage and the Channel Parameter
Why it's important: A
channel parameter is an optional
parameter that allows you to track usage under your client ID by assigning
a distinct channel to each of your applications. Channel parameters do not
need to be registered to your client ID. By simply adding the channel
parameter to your API request, they will begin to appear in your support
portal usage reports 1-2 days after implementation. It is up to you to
decide where your channels are implemented and, hence, how your usage is
aggregated. Please decide prior to launch if your application should
integrate channel parameters to track your application usage:
channel parameter must use the following format:
- Must be an ASCII alphanumeric string.
- Period (
.), underscore (
_) and hyphen (
-) characters are allowed.
channelparameter is case-insensitive; upper-case, mixed-case, and lower-cased
channelparameters are merged into their lower-case equivalent. For example, usage on the
CUSTOMERchannel is combined with the usage on the
You may implement up to 2,000 distinct channels per client ID.
To use the
channel parameter, include it in the request URL together with the
client parameter used for passing the client ID.
Please note that the channel parameter must be a statically assigned value per application. It must not be generated dynamically and used to track individual users.
Remove Obsolete Parameters from your API Requests (eg.
you must include your client ID. You must also remove any
key parameters. If your request includes both a client ID and a
key, it will fail.
Please follow the Google Maps APIs for Work guide for complete information on how to correctly format Google Maps APIs for Work requests per API: https://developers.google.com/maps/premium/previous-licenses/