Client IDs and signatures

When using the
Google Maps Platform web services
with a Google Maps APIs for Work license, two
authentication parameters are required: client ID and unique
digital signature (instead of the API key).

If you're switching from the free API web services to a
Google Maps APIs for Work implementation, you must remove
the key parameter from your requests.
Google Maps Platform web services will deny requests made with both
a client ID and a key.

Your client ID and signature

Upon purchasing your Google Maps APIs for Work license, you will receive a
welcome email from Google that contains your client ID
and your private cryptographic key.

Your client ID is used to access the special features of
Google Maps APIs for Work—you must provide a client ID when accessing
any of the API libraries or services. All client IDs begin with a
gme- prefix. Pass your client ID as the value of the
client parameter.

A unique digital signature is generated using your private
cryptographic key. Pass this signature as the value of the signature parameter.
You can find more information about generating a signature below, in the
section on digital signatures.

If you have lost your client ID or private cryptographic key,
you can recover it by logging in to the
Google Cloud Support Portal
and clicking Maps: Manage Client ID from the links on the
left of the page.

Optional parameter for reports

In addition to the authentication parameters, the following parameter is optional
with Google Maps APIs for Work requests:

channel is used to provide additional reporting detail, by
grouping different channels separately in your reports. Refer to the
Channel reports section of the Google Maps APIs for Work
web services Quota and Reporting document.

Digital signatures

Requests to the web service APIs by Google Maps APIs for Work
customers require a digital signature, generated using the
private cryptographic key provided to you in your welcome email.

The signing process combines a URL and the key together using an encryption
algorithm. The resulting unique signature allows our servers to verify that
any site generating requests using your client ID are authorized to do so.
The signature is also unique per URL, ensuring that requests that use
your client ID cannot be modified without requiring a new signature to
be generated.

Your private cryptographic key

Your private cryptographic URL-signing key will be issued with your client ID
and is a "secret shared key" between you and Google. This signing key is yours
alone and is unique to your client ID. For that reason, please keep your
signing key secure. This key should not be passed within any
requests, stored on any websites, or posted to any public forum. Anyone
obtaining this signing key could spoof requests using your identity.

Note: This private cryptographic signing key is
not the same as the API keys issued by the Google Cloud Platform Console.

If you've lost your private cryptographic key, log in to the
Google Cloud Support Portal and click
Maps: Manage Client ID to retrieve it.

Generate a digital signature

Attempting to access the Google Maps Platform web services with an invalid signature will
result in a HTTP 403 (Forbidden) error. As you convert your applications
to use URL signing, make sure to test your signatures to ensure they
initiate a valid request. You should first test whether the original URL
is valid as well as test whether you generate the correct
signatures.

Follow these steps to create a digital signature for your request:

Construct the request URL without the signature, making sure to include your
client parameter. Note that any non-standard characters will need to
be URL-encoded. For example,
for the Directions API, construct the URL as follows:

Note: All Google services require UTF-8 character encoding (which
implicitly includes ASCII). If your applications operate using other
character sets, make sure they construct URLs using UTF-8 and properly
URL-encode them.

Strip off the domain portion of the request, leaving only the path
and the query. For example, for the Directions API:

Retrieve your private key, which is
encoded in a modified Base64
for URLs, and sign the URL above using the HMAC-SHA1 algorithm. You may need to
decode this key into its original binary format. Note that in most
cryptographic libraries, the resulting signature will be in binary
format.

Note: Modified Base64 for URLs replaces the + and /
characters of standard Base64 with - and _
respectively, so that these Base64 signatures no longer need to be
URL-encoded.

Encode the resulting binary signature using the modified
Base64 for URLs to convert
this signature into something that can be passed within a URL.

Attach this signature to the URL within a signature parameter.
For example, for the Directions API:

C#

The example below uses the default
System.Security.Cryptography library to sign a URL request.
Note that we need to convert the default Base64 encoding to implement a
URL-safe version.
(Download
the code.)

For testing purposes, you can test the following URL and private key to
see if it generates the correct signature. Note that this private key is
purely for testing purposes and will not be validated by any Google
services.