API Key Best Practices

API keys are required for apps and projects that use the Google Maps Platform APIs and SDKs. This document identifies the intended use of API keys, how to protect them as you would other credentials, and which restrictions are appropriate for your projects.

What are API keys?

API keys are project-centric credentials that serve two purposes:

  • Project Identification.
    Identify the app or the project that's making a call to the API or SDK.
  • Project Authorization.
    Check whether the calling app has been granted access to call the API or SDK and has enabled the API or SDK in the project.

When an API key is created, it is associated with a project. By identifying the calling project, an API key enables usage information to be associated with that project, and helps ensure calls from other projects are rejected.

Protecting API keys

You should secure the API keys in your application for all Google Maps Platform products that your application uses. You can secure API keys by designating restrictions and by implementing best practices that are appropriate for the Google Maps Platform APIs in your application. Publicly exposing unsecured credentials can result in unintended use, which could lead to unexpected charges on your account.

The following practices describe strategies to help protect your API keys. The applicable practices for an individual Google Maps Platform product, such as Maps JavaScript API, are listed in the API key restrictions and best practices section.

  • Restrict your API keys. You can best protect your API key by restricting it to specific IP addresses, referrer URLs or mobile apps, and specific APIs, as this significantly reduces the impact of a key compromise.

    You can specify application and API restrictions for a key from the console by opening the Credentials page and then either creating a new API key with the settings you want, or editing the settings of an API key. See section Restricting API keys for full details.

  • Use independent API keys for different apps. This limits the scope of each key. If an API key is compromised, you can delete and revoke the impacted key without needing to update your other API keys.
  • Delete unneeded API keys.

    To delete an API key:

    1. Visit the credentials panel.
    2. Select the API key you want to delete.
    3. Click the Delete button near the top of the page.
    4. When the Delete credential popup appears, click DELETE.

  • Exercise caution when regenerating API keys. If the time needed to migrate your apps from the old API key to the new, regenerated API key exceeds 24 hours, the instances that are not updated will become broken as they reference the old key, which is destroyed 24 hours after regeneration.

    When you regenerate an API key, the following things happen:

    • A new key results from the regeneration process.
    • The new key receives all the restrictions from the old key.
    • A 24-hour window begins, marking the amount of time until the old key is destroyed.

  • Monitor usage of your API for anomalies. If you observe unauthorized usage, rotate your keys and notify Google.

    Before rotating a key, preserve the restrictions associated with the key by making a copy of them in a file.

  • On apps that use Maps Web Service APIs or Static Web APIs, use the following methods to safeguard your apps and API keys:

    • Do not embed API keys or signing secrets directly in code. Instead of directly embedding API keys or any other private information in you application's code, put them in environment variables or in include files that are stored separately from the bulk of your code—outside the source repository of your application. Then, if you share your code, the API keys or signing secrets will not be included in the shared files.
    • Do not store API keys or signing secrets in files inside your application's source tree. If you store API keys or any other private information in files, keep the files outside your application's source tree to help ensure your keys or other private information do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.
    • Review your code before publicly releasing it. Ensure that your code does not contain API keys, signing secrets or any other private information before you make your code publicly available.

  • On mobile apps that use Web Service APIs or Static Web APIs, consider one or more of the following techniques to further safeguard your API keys or signing secrets:

Restricting API keys

API keys are credentials, and you should manage them carefully. At a minimum, follow the recommendations below to keep your keys safe, and to make sure that you have restrictions in place to reduce the impact of compromised API keys.

You can restrict an API key by specifying an Application restriction, or one or more API restrictions.

Application restrictions limit usage of API keys to specific sites (IP address and web site) or specific platforms (Android and iOS). You can select at most one restriction from this category (see Google Maps Platform APIs by Platform).

API restrictions limit usage of API keys to one or more Google Maps Platform APIs or SDKs. Requests to use APIs or SDKs associated with an API key will be processed. Requests to use APIs or SDKs not associated with an API key will fail. For an API key, you can specify as many API restrictions as needed. Make sure the APIs or SDKs associated with an API key support the application restriction set for that API key.

To set an application restriction for an API key

  1. Visit the credentials panel.
  2. Select the API key that you want to set a restriction on. The API key property page appears.
  3. Under Key restrictions, select Application restrictions.
    Select one of the restriction types and supply the requested information following the restriction list.
    Restriction type Description
    HTTP referrers

    Accept requests from the list of websites that you supply.

    Below the types, specify one or more referrer web sites. Wildcard characters are acceptable for naming similar web sites. For example, *.google.com accepts all sites ending in google.com, such as https://developers.google.com.

    IP addresses

    Accept requests from the list of web server IP addresses that you supply.

    Below the types, specify one IPv4 or IPv6 address or a subnet using CIDR notation (e.g. 192.168.0.0/22). If you need to enter another entry, a new box appears after you complete adding the previous entry.

    Android apps

    Add your package name and SHA-1 signing-certificate fingerprint to restrict usage to your Android app.

    Below the types, add the SHA-1 signing-certificate fingersprint and your Android package name from your AndroidManifest.xml file.

    iOS apps

    Accept requests from the iOS app with the bundle identifier that you supply.

    Below the types, select the appropriate iOS bundle identifier from the list.
  4. Click Save.
    The restriction becomes part of the API key definition after this step. If you fail to provide the appropriate details or do not click “Save”, the API key will not be restricted. (For further information, see the Get an API Key guide for the specific API or SDK you are interested in.)

To set an API restriction for an API key

  1. Go to the credentials panel.
  2. Select the API key that you want to restrict.
    The Restrict and rename API key page appears.
  3. Under API restrictions:
    • Click Restrict key.
    • Click the Select APIs drop-down and select the APIs or SDKs you want your application to access using the API key. (If an API or SDK is not listed, you need to enable it.)
  4. Click Save.
    The restriction becomes part of the API key definition after this step. If you fail to provide the appropriate details or do not click “Save”, the API key will not be restricted. (For further information, see the Get an API Key guide for the specific API or SDK you are interested in.)

API key restrictions and best practices

The following tables list the appropriate API key restrictions and best practices for each Google Maps Platform API, SDK or Service.

Websites with Maps JavaScript, Embed or Static APIs

API/SDK/Service Application Restriction(1) API Restriction(1) Best Practices
Maps JavaScript API(2) HTTP referer restriction Maps JavaScript API
Directions Service, Maps JavaScript API HTTP referer restriction Directions API, Maps JavaScript API
Distance Matrix Service, Maps JavaScript API HTTP referer restriction Distance Matrix API, Maps JavaScript API
Elevation Service, Maps JavaScript API HTTP referer restriction Elevation API, Maps JavaScript API
Geocoding Service, Maps JavaScript API HTTP referer restriction Geocoding API, Maps JavaScript API
Places Library, Maps JavaScript API HTTP referer restriction Places API, Maps JavaScript API
Maps Embed API HTTP referer restriction Maps Embed API
Maps Static API HTTP referer restriction Maps Static API
Street View Static API HTTP referer restriction Street View Static API

Apps and servers using web services

API/SDK/Service Application Restriction(1) API Restriction(1) Best Practices
Directions API IP address restriction(4) Directions API
Distance Matrix API IP address restriction(4) Distance Matrix API
Elevation API IP address restriction(4) Elevation API
Geocoding API IP address restriction(4) Geocoding API
Geolocation API IP address restriction(4) Geolocation API
Places API(5) IP address restriction(4) Places API
Roads API IP address restriction(4) Roads API
Time Zone API IP address restriction(4) Time Zone API

Android apps

API/SDK/Service Application Restriction(1) API Restriction(1) Best Practices
Maps SDK for Android Android restriction Maps SDK for Android
Places SDK for Android Android restriction Places API

iOS apps

API/SDK/Service Application Restriction(1) API Restriction(1) Best Practices
Maps SDK for iOS iOS restriction Maps SDK for iOS
Places SDK for iOS iOS restriction Places API

1 You may use an unrestricted API key with any Google Maps Platform API or SDK. However, it is highly recommended that you restrict your API keys, especially in following scenarios:

  • The test environment will be or is publicly visible.
  • The application that uses an API key is ready to be used in a production environment.

2 For mobile applications, consider using the native Maps SDK for Android and Maps SDK for iOS.

3 For the Maps Static API and Street View Static API, in addition to an API key, you need to provide a digital signature to exceed the daily quota of 25,000 map loads.

Note: Shared secrets used for signing require at least the same level of security as API keys used with Maps Web Service APIs.

Also, if you need to sign your image requests dynamically, do it server side. If your apps rely on client-side input for generating the static images, secure them using one or more of the following techniques:

If you sign your requests, also review how many unsigned requests you wish to allow per day, and adjust your unsigned request quotas accordingly.

4 IP restrictions might be impractical, such as in mobile applications and cloud environments that rely on dynamic IP addresses. When using Maps Web Service APIs in these scenarios, secure your apps using one or more of the following techniques:

5 For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS.