Ensuring your team has access to the necessary resources

Why it's important: Your welcome letter is your Google Maps Platform Premium Plan
starter kit and perhaps also your first aid kit. It contains critical bits of
information such as your Google Cloud Platform Console project ID, your client ID and your
cryptographic key, which are necessary to begin using the
Premium Plan. It also contains all the information
you need to contact the Premium Plan Support team
if you experience any technical issues with any of the Google Maps
APIs.

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 allows you to file
support cases with the Premium Plan Support team
if 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. If
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 if 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:

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 up-to-date support hotline number. Please note that
while you are welcome to use 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 in this document:

Optimizing your application

Configure a 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 *google.com
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 Platform Premium Plan or
a previous Google Maps APIs for Work or Google Maps for Business license.

Navigate to the Resources tab.

Select the list of domains used by the Google Maps Platform
family. (Here's the
direct link.)

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 API and use case.

Load the APIs over the correct SSL hostname

Why it's important: Applications that load the Maps APIs
over SSL should do so from https://maps.googleapis.com
rather than the legacy hostname, https://maps-api-ssl.google.com.

Authorize your SSL domains for use with the
Maps JavaScript API

Why it's important: When using the Maps JavaScript 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 the guide to
troubleshooting authorization.

Note: Once your Premium Plan license has expired, the link
to the Maps: Manage Client ID no longer appears in the left navigation
bar of the Support Portal. To access the Client ID management tool,
follow this link.

Select the proper API version

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.

In particular, it's critical to understand the versioning scheme used by the
Maps JavaScript API, so that you avoid
accidentally using an improper version of the API in your environment.

For example, it may be suitable to use the experimental
version of the API in your development or test environment, but we strongly
discourage the use of the experimental 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.

Choose between client-side and server-side design

Why it's important: Choosing a client-side 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
(that is, outside of your application). Alternatively, a client-side approach
should be used for the portions of your applications which interact with
your users (that is, 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 before designing or launching applications that rely on
server-side calls.

Optimize quota usage

Why it's important: Understanding the way your application consumes
quota, known as Maps APIs Credits, helps you to reduce the amount you pay. For
example, if you're using the Maps JavaScript API, your
application consumes Maps APIs Credits for each
map load. See the guide to
Premium Plan
usage rates and limits.

Manage your web services quota usage

Why it's important: By default, the shared web services quota
is set at 100,000 daily free requests.
For a more detailed quota breakdown per API, see the guide to
usage limits. To confirm how much quota
is available to your project, please file a
support case.

Before launching your service, it is critical that you understand the
different quota related errors
(for example, OVER_QUERY_LIMIT, 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 FAQ.
For information on the status codes returned by each API, consult the
developer's guide for that API. For example, see the guide to
Directions API status codes.
Understanding and implementing these concepts will greatly reduce the chances
of your application exceeding its allowed quota, being blocked by Google,
and/or breaking.

Perform load testing on your app

Why it's important: Use load testing of your application to ensure
it can handle high volumes of requests without exceeding your quotas for the
Maps APIs.

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.

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. If you need higher quota for your App Engine
application, you can also enable
billing, although this should rarely be necessary.

Migrating your application from a standard to a premium
license

Include your client ID or API key in API requests

Why it's important: One of the most important things you can do for
your application is to ensure you include your client ID
(gme-yourclientid) or your API key (which looks
something like this: AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0) in
your API requests. The client ID or API key identifies your requests as a
Google Maps Platform Premium Plan request.

You must include your client ID or API key in your applications in order to
benefit from any features specific to Premium Plan.
Inclusion of your client ID or API key is also necessary in order to receive
technical support and to ensure your application is under our SLA.

For most of the APIs, you can choose whether to use a client ID or API key.
Your client ID is included in the welcome letter which was issued to your
organization's primary contact(s). You can generate your own API key or keys
on the
Google Cloud Platform Console.

Include either the API key or the client ID in API
requests, but not both

Why it's important: In order to correctly load the
Maps JavaScript API, or to send a request to other Google Maps
APIs, you must include either your client ID
or your API key, but not both. If you choose to use a client
ID, you must remove any key parameters. If your request includes
both a client ID and a key, your application may experience unexpected behavior or errors.

When using a client ID, authorize your domains for use with the
Maps JavaScript API

Why it's important: To prevent unauthorized sites from
using your client ID, the Maps JavaScript API
requires that you authorize all domains with our support team for all
sites which will use your client ID. (URL registration is not required if
you use an API key instead of a client ID.) If there is no match between the
URLs authorized to use your client ID and the
site trying to use your client ID, your site will be unable
to use the API with your client ID. You can authorize domains at any time
so please ensure that you have authorized the domains for all your sites in
advance of your launch.

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.

When using a client ID, sign web service requests using a
signature generated with your private cryptographic key

Why it's important: Your private, cryptographic key is used to
generate digital signatures which communicate to Google that
your requests have come from a trusted source. Our web service APIs require that you add a digital
signature to your requests, if you use a client ID for authentication. This
adds a layer of security on top of your request which will better safeguard
the quota associated with your client ID. Your cryptographic key (for example,
vNIXE0xscrmjlyV-12Nj_BvUPaw=) is included in your welcome letter
which was issued to your organization's primary contact(s).

Note: The cryptographic key is used to
generate signatures. Do not append it 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.
Premium Plan web service requests which are not
properly signed will be rejected by our servers so it's critical your
application properly signs request prior to launch. See the guide to
authentication
and authorization.

Track application usage

Why it's important: As a Premium Plan
customer, you have access to detailed reports on your application's usage,
including requests made, credits consumed, errors returned, and more. See the
guide to reports.

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 adding the channel parameter to your API request, the usage results per
channel 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.

The channel parameter must use the following format:

Must be an ASCII alphanumeric string.

Period (.), underscore (_) and hyphen (-)
characters are allowed.

The channel parameter is case-insensitive; upper-case, mixed-case,
and lower-cased channel parameters are merged into their
lower-case equivalent. For example, usage on the CUSTOMER channel
is combined with the usage on the customer channel.

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.