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.

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 table lists the appropriate API key restrictions and best practices for each Google Maps Platform API, SDK or Service.

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
Maps SDK for iOS iOS restriction Maps SDK for iOS
Places SDK for iOS iOS restriction Places API
Maps JavaScript API(2) HTTP referer restriction Maps JavaScript API
Directions Service, Maps JavaScript API HTTP referer restriction Directions API(3)
Distance Matrix Service, Maps JavaScript API HTTP referer restriction Distance Matrix API(3)
Elevation Service, Maps JavaScript API HTTP referer restriction Elevation API(3)
Geocoding Service, Maps JavaScript API HTTP referer restriction Geocoding API(3)
Places Library, Maps JavaScript API HTTP referer restriction Places API(3)
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
Directions API IP address restriction(5) Directions API
Distance Matrix API IP address restriction(5) Distance Matrix API
Elevation API IP address restriction(5) Elevation API
Geocoding API IP address restriction(5) Geocoding API
Geolocation API IP address restriction(5) Geolocation API
Places API(6) IP address restriction(5) Places API
Roads API IP address restriction(5) Roads API
Time Zone API IP address restriction(5) Time Zone 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 In addition to the API restriction for Maps JavaScript API.

4 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.

5 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:

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