For apps and projects that use the Google Maps Platform APIs and SDKs, youmust use API keys or, if supported, Oauth, to prevent unauthorized use andcharges. If you use API keys, for maximum security, restrict your API keys whenyou create them. These best practices show you how to restrict them.
In addition to applying application and API key restrictions, follow anysecurity practices that apply to specific Google Maps Platform products.For example, see the Maps JavaScript API below inRecommended application and API restrictions.
If your API keys are already in use, review the recommendations below inIf you are restricting or regenerating an API key that's in use.
For more details about digital signatures, see theDigital Signature Guide.
Recommended best practices
For increased security and to avoid being billed for unauthorized use, followthese API security best practices for all Google Maps Platform APIs, SDKs, orservices:
Recommended for all API key uses
Restrict your API keys
Use separate API keys for each app
Delete unused API keys
Check your API key usage
Be careful when regenerating API keys
Additional recommendations for websites using Static Web APIs
Protect apps using Static Web APIs
Additional recommendations for apps using web services
Protect apps using web services
Additional recommendations for iOS and Android mobile applications
Protect mobile apps using web Service or Static Web APIs
If you are restricting or regenerating an API key that's in use
Before you change the API key, Check your API key usageThis step is especially important if you are adding restrictions after the keyis in use.
After you change the key, update all of your apps with the new API keys, asneeded.
If there is no active abuse of your API key, you can migrate your apps tomultiple new API keys at your own pace, leaving the original API key untoucheduntil you only see one type of traffic, to which you can then restrict the APIkeys with an application restriction. For further instructions, seeMigrate to multiple API keys.
Monitor the usage over time, and see when specific APIs, platform types, anddomains have migrated off the old API key before you choose to restrict ordelete the old key. For more information, seeReporting and monitoring andMetrics.
If your API key has been compromised, you want to move more quickly to secureyour API key and stop the abuse. In Android and iOS apps, keys aren't replaceduntil customers update their apps. Updating or replacing keys in JavaScript orweb service apps is much more straightforward, but it still may requirecareful planning and fast work.
For more information, seeHandle unauthorized use of an API key.
Restrict your API keys
Best practice is to always restrict your API keys with an applicationrestriction and one or more API restrictions. For suggested restrictions by API,SDK, or JavaScript service, seeRecommended application and API restrictions below.
Application restriction You can limit the use of an API key to specificplatforms: Android or iOS applications, or specific websites for client-sideapplications, or specific IP addresses or CIDR subnets for server-side appsissuing web service REST API calls.
You restrict a key by adding one or more application restrictions of the typesyou want to authorize, after which only requests originating from thesesources are permitted.
API restrictions You can restrict which Google Maps Platform APIs,SDKs, or services on which your API key can be used. API restrictions onlyallow requests to the APIs and SDKs you specify. For any given API key, youcan specify as many API restrictions as needed. The list of available APIsincludes all APIs enabled on a project.
Set an application restriction for an API key
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
Select the API key that you want to restrict.
On the Edit API key page, under Key restrictions, selectSet an application restriction.
Select one of the restriction types and supply the requested informationfollowing the restriction list.
Restriction type Description Websites Specify one or more referrer websites. - The universally-supported referrer URI schemes are
httpsandhttp. - Always provide the full referrer URI, including the protocol scheme, hostname and optional port (e.g.,
https://google.com). - You can use wildcard characters to authorize all subdomains. For example,
https://*.google.comaccepts all sites ending in.google.com. Note that if you specify www.domain.com, it acts as a wildcard www.domain.com/*, and authorizes any subpath on that hostname. - Be careful when authorizing full-path referrers, for example,
https://google.com/some/path, as, by default, most current browsers strip the path from cross-origin requests.
IP addresses Specify one or more IPv4 or IPv6 addresses, or subnets using CIDR notation. The IP addresses must match the source address the Google Maps Platform servers observe. If you use network address translation (NAT), this address typically corresponds to your machine's public IP address. Android apps Add the Android package name (from the AndroidManifest.xmlfile) and the SHA-1 signing certificate fingerprint of each Android application you want to authorize. If you use Play App Signing, to fetch the signing certificate fingerprint, see Working with API Providers. If you manage your own signing key, see Self-signing your application or refer to the instructions for your build environment.iOS apps Add the bundle identifier of each iOS application you want to authorize. For recommendations for an application restriction, seeRecommended application Restriction.
- The universally-supported referrer URI schemes are
Select Save.
Set API restrictions for an API key
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
Select the API key that you want to restrict.
On the Edit API key page, under API restrictions:
Select Restrict key.
Open Select APIs and select the APIs or SDKs you wantyour application to access using the API key.
If an API or SDK is not listed, you need to enable it. For details, seeTo enable one or more APIs or SDKs.
Select Save.
The restriction becomes part of the API key definition after this step.Be sure you provide the appropriate details and select Save to save yourAPI key restrictions. For further information, see theGet an API Key guide in the documentation for the specific API or SDKyou are interested in.
For recommended API restrictions, seeRecommended API Restrictions.
Check your API key usage
If you're restricting API keys after they've been created, or if you want to seewhat APIs are being used by a key so you can restrict them, you want to checkyour API key usage. These steps show you in which services and API methodsan API key is being used. If you see any usage beyondGoogle Maps Platform services, investigate to determine if you need to addmore restrictions to avoid unwanted use.You can use the Google Maps Platform Cloud Console Metrics explorer to helpdetermine which API and application restrictions to apply to your API key:
Determine the APIs that use your API key
Choose the correct type of application restriction using the Metrics explorer
Determine the APIs that use your API key
The following metrics reports allow you to determine which APIsare using your API keys. Use these reports to do the following:
- See how your API keys are used
- Spot unexpected usage
- Help verify if an unused key is safe to delete. For information about deletingan API key, see Delete unused API keys.
When applying API restrictions, use these reports to create a list of APIs toauthorize, or to validate automatically-generated API key restrictionrecommendations. For more information about recommended restrictions, seeApply recommended restrictions. For more information about usingthe Metrics explorer, seeCreate charts with Metrics explorer.
Go to theGoogle Cloud Console's Metrics explorer.
Log in and select the project for the API keys you want to check.
Go to the Metrics explorer page for your type of API:
For API keys using any API except the Maps Embed API: Go toMetrics explorer page.
For API keys using Maps Embed API: Go toMetrics Explorer.
Inspect each API key:
Select ADD FILTER.
Select the label
credential_id.Select the value corresponding to the key you want to inspect.
Note which APIs this API key is being used for, and confirm the use isexpected.
Once done, select Remove filterdelete at the end of the active filterline to delete the extra filter.
Repeat for any remaining keys.
Restrict your API keys to only the APIs that are being used.
If you spot unauthorized use, seeHandle unauthorized use of an API key.
Choose the correct type of application restriction using the Metrics explorer
After you have verified and taken any needed actions to ensure your API key isonly used for the Google Maps Platform services it is using, alsoensure the API key has the correct application restrictions.
If your API key has recommended API key restrictions, apply them. For moreinformation, see Apply recommended API key restrictions.
If your API key doesn't have restriction recommendations, determine the type ofapplication restriction to apply, based on the reported platform_type usingthe Metrics explorer:
Go to theGoogle Cloud Console's Metrics explorer.
Log in and select the project for the APIs you want to check.
Go to this Metrics explorer page:Metrics explorer.
Inspect each API key:
Select ADD FILTER.
Select the label
credential_id.Select the value corresponding to the key you want to inspect.
Once done, select Remove filterdelete at the end of the active filterline to delete the extra filter.
Repeat for any remaining keys.
Once you have the platform type for your API keys, apply the applicationrestriction for that
platform_type:PLATFORM_TYPE_JS- Apply Website restrictions on the key.
PLATFORM_TYPE_ANDROID- Apply Android application restrictions on the key.
PLATFORM_TYPE_IOS- Apply iOS application restrictions on the key.
PLATFORM_TYPE_WEBSERVICE- You may have to rely IP address restrictions on the key, to properlyrestrict it. For further options for Maps Static API andStreet View Static API, seeProtect apps using Static Web APIs.For further instructions for Maps Embed API, seeWebsites with the Maps Embed API.
- My API key is using multiple platform types
- Your traffic can't be properly secured with just a single API key. You needto migrate to multiple API keys. For more information, seeMigrate to multiple API keys.
Use separate API keys for each app
This practice limits the scope of each key. If one API key is compromised, youcan delete or regenerate the impacted key without needing to update your otherAPI keys. You can create up to 300 API keys per project. For more information,seeLimits on API keys.
While one API key per application is ideal for security purposes, you can userestricted keys on multiple apps as long as they use the same type ofapplication restriction.
Apply recommended API key restrictions
For some project owners and editors, the Google Cloud Console suggestsspecific API key restrictions to unrestricted API keys based on theirGoogle Maps Platform usage and activity.
If available, recommendations appear as pre-filled options on theGoogle Maps Platform Credentials page.
Reasons you may not see a recommendation, or an incomplete one
You are (also) using the API key on other than Google Maps Platformservices. If you see usage on other services, don't apply therecommendation without first doing the following:
Verify that the API usage you see in the Google Cloud Console Metricsexplorer is legitimate.
Manually add missing services to the list of APIs to be authorized.
Manually add any missing application restrictions for the services addedto the API list. If your other added would require a different type ofapplication restrictions, seeMigrate to multiple API keys.
Your API key is not used in client-side SDKs or APIs.
You use the API key in a low-volume app or website that has not seen usageover the last 60 days.
You have created a new key very recently, or you have very recently deployedan existing key in a new app. If this is the case, just wait a few more daysto allow the recommendations to update.
You are using the API key in multiple applications that would requireconflicting types of application restrictions, or you are using the sameAPI key in too many different apps or websites. In either case, as a bestpractice, you should migrate to multiple keys. For more details, seeMigrate to multiple API keys.
Reasons you might see recommendations that are not visible in the charts
Your app or website sent only very short traffic bursts. In this case, switchfrom a CHART view to display a TABLE or BOTH, as the usage isstill visible in the legend. For more information, seeToggling the chart's full legends.
Your traffic is from the Maps Embed API. For instructions, seeDetermine the APIs that use your API key.
The traffic from the app or website is outside the date range available inthe Google Cloud Console Metrics explorer.
To apply recommended restrictions
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
If available, select Apply recommended restrictions.
Note: If you don't see any recommended restrictions, seeSet API restrictions for an API key to set appropriaterestrictions.
Select Check API usage to verify which services the API key is beingused on. If you see other than Google Maps Platform services, pauseto manually review the recommendation steps above. See the troubleshootingsteps at the beginning of sectionApply recommended API key restrictions.
Double-check that the pre-filled restrictions match the websites and appswhere you expect to use your API key.
Best Practice: Document and remove any application or API restrictionsthat are not affiliated with your services. If something breaks due to anunexpected dependency, then you can add the required apps or APIs back in.
If you recognize that an app, website or API is clearly missing from yourrecommendation, add it manually or wait a couple of days to allow therecommendation to update.
If you need further help with your suggested recommendation,contact support.
Select Apply.
What to do if your application gets rejected after applying a recommendation
If you notice that an app or website gets rejected after applying a restriction,look for the application restriction you need to add in the API response errormessage.
For client-side SDKs, see below:
- Maps JavaScript API apps: see the browser debug console
- Android apps: useAndroid Debug Bridge (adb) or Logcat
- iOS apps: see Viewing Log Messages
To check your required API restrictions, seeDetermine the APIs that use your API key.
If you are unable to determine which restrictions to apply:
- Document the current restrictions for future reference.
- Remove them temporarily while you investigate the issue. You can check yourusage over time using the steps in Check your API key usage.
- If needed, contact support.
Delete unused API keys
Before you delete an API key, make sure that it is not used in production. Ifthere is no successful traffic, the key is likely safe to delete. For moreinformation, see Check your API key usage.
To delete an API key:
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
Select the API key you want to delete.
Select the Delete button near the top of the page.
On the Delete credential page, select Delete.
Deleting an API key takes a few minutes to propagate. Afterpropagation completes, any traffic using the deleted API key is rejected.
Be careful when regenerating your API keys
Regenerating an API key creates a new key that has all the old key'srestrictions. This process also starts a 24-hour timer after which the old APIkey is deleted.
During this time window, both the old and new key are accepted, giving you achance to migrate your apps to use the new key. However, after this time periodelapses, any apps still using the old API key stop working.
Before regenerating an API key:
First try to restrict your API keys as described inRestrict your API keys.
If restricting your API key is not possible due to conflicting applicationrestriction types, migrate to multiple new (restricted) keys as described inMigrate to multiple API keys. Migratinglets you control the migration and roll out timeline to the new API keys.
If the preceding suggestions aren't possible, and you must regenerate yourAPI key to prevent unauthorized use, then follow these steps:
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
Open the API key you want to regenerate.
At the top of the page, select Regenerate key.
Select Replace key.
Note: If necessary, you can roll back any key that has been regenerated toits previous version. There are no time limits for roll-back.
To roll back a regenerated key
Open the Google Cloud ConsoleGoogle Maps Platform Credentials page.
Open the API key you want to roll back.
Select Revert to previous key.
In the Revert dialog, select Revert key.
Upon rolling back, the former "new" version of the key becomes the previousversion, and a new 24-hour deactivation timer is set for it. It is possible torevert between these two key values until you regenerate the key again.
If you regenerate the key again, it overwrites the old inactive key value.
Migrate to multiple API keys
To migrate from using one API key for multiple apps to a single unique API keyfor each app, do the following:
Identify which apps need new keys:
- Web apps are the easiest to update, since you control all of the code.Plan to update all of your web-based apps' keys.
- Mobile apps are much harder, since your customers must update their appsbefore the new keys can be used.
Create and restrict the new keys: Add both an application restrictionand at least one API restriction. For more information, seeRecommended best practices.
Add the new keys to your apps: For mobile apps, this process maytake months until all of your users update to the latest app with the newAPI key.
Protect apps using Static Web APIs
Static Web APIs, such as the Maps Static API andStreet View Static API, are similar to web service API calls.
You call both using a simple HTTPS REST API, and you typically generate the APIrequest URL on the server. However, instead of returning a JSON response, StaticWeb APIs generate an image that you can embed in generated HTML code. Moreimportantly, it is generally the end-user client, not the server, that callsthe Google Maps Platform service.
Use a digital signature
As a best practice, always use digital signatures in addition to anAPI key. Also, review how many unsigned requests you wish to allow per day andadjust your unsigned request quotas accordingly.
For more details about digital signatures, see theDigital Signature Guide.
Protect your signing secret
To protect Static Web APIs, don't embed your API signing secrets directly incode or in the source tree, or expose them in client-side applications. Followthese best practices for protecting your signing secrets:
Sign your requests server-side, not on the client. If you do the signingclient-side in JavaScript, you expose it to anyone visiting your site.Therefore, for dynamically-generated images, always generate your signed MapsStatic API and Street View Static API request URLs server-side when servingthe web page. For static web content, you can use the Sign a URL nowwidget on the Cloud Console Google Maps Platform Credentials page.
Store signing secrets outside of your application's source code and source tree.If you put your signing secrets or any other private information inenvironment variables or include files that are stored separately and thenshare your code, then signing secrets are not included in the shared files. Ifyou store signing secrets or any other private information in files, keepthe files outside your application's source tree to keep your signing secretsout of your source code control system. This precaution is particularlyimportant if you use a public source code management system, such as GitHub.
Protect your API key in apps using web services
Store API keys outside of your application'ssource code or source tree. If you put your API keys or any otherinformation in environment variables or include files that are storedseparately and then share your code, the API keys are not included in theshared files. This is particularly important if you use a public source codemanagement system, such as GitHub.
Protect your API key and signing secret in mobile apps using web services or Static Web APIs
To protect mobile apps, use a secure keystore or secure proxy server:
Store the API key or signing secret in a secure keystore. This step makesit harder to scrape API keys and other private data directly from theapplication.
Use a secure proxy server. The proxy server provides a solid source forinteracting with the appropriate Google Maps Platform API. For moreinformation about using a proxy server, seeLiving Vicariously: Using Proxy Servers with the Google Data API Client Libraries.
Construct your Google Maps Platform requests on the proxy server.Don't allow clients to relay arbitrary API calls via the proxy.
Post-process the Google Maps Platform responses on your proxy server.Filter out data that the client doesn't need.
Handle unauthorized use of an API key
If you detect use of your API key that is unauthorized, do the following toaddress the problem:
Restrict your keys: If you've used the same key in multiple apps,migrate to multiple API keys, and use separate API keys for each app.For more details, see:
- Restrict your API keys
- Migrate to multiple API keys
- Use separate API keys for each app
Only regenerate keys if you are unable to restrict them. Read throughsection Be careful when regenerating API keysbefore proceeding.
If you are still having issues or need help,contact support.
Recommended application and API restrictions
The following sections suggest appropriate application and API restrictions foreach Google Maps Platform API, SDK or service.
Recommended API Restrictions
The following guidelines for API restrictions apply to the entireGoogle Maps Platform:
Restrict your API key to only the APIs you are using it for, with thefollowing exceptions:
If your app uses the Places SDK for Android orPlaces SDK for iOS, authorize the Places API.
If your app uses Maps JavaScript API, alwaysauthorize it on your key.
If you also use any of the following Maps JavaScript APIservices, you should in addition also authorize the following APIs:
Service API restriction Directions Service, Maps JavaScript API Directions API Distance Matrix Service, Maps JavaScript API Distance Matrix API Elevation Service, Maps JavaScript API Elevation API Geocoding Service, Maps JavaScript API Geocoding API Places Library, Maps JavaScript API Places API
Some examples:
You are using the Maps SDK for Android andPlaces SDK for Android, so you include theMaps SDK for Android and Places API asAPI restrictions.
Your website uses the Maps JavaScript APIElevation Service andthe Maps Static API, so you add API restrictions for all of thefollowing APIs:
- Maps JavaScript API
- Elevation API
- Maps Static API
Recommended application Restriction
Websites with Maps JavaScript API or Static Web API
For websites using Maps JavaScript services or Static Web APIs, use theWebsites application restriction.
Use for websites using these JavaScript services and APIs:
1 For mobile applications, considerusing the nativeMaps SDK for Androidand Maps SDK for iOS.
2 See alsoProtect mobile apps using web service or Static Web APIs.
Websites with the Maps Embed API
While using the Maps Embed API is free of charge, you should stillrestrict any used API key to prevent abuse on other services.
Best practice: Create a separate API key for Maps Embed APIuse, and restrict this key to only the Maps Embed API. Thisrestriction sufficiently secures the key, preventing its unauthorized use on anyother Google service.
If you are unable to separate your Maps Embed API usage to aseparate API key, secure your key using the Websitesapplication restriction.
Apps and servers using web services
For apps and servers using web services, use the IP addressesapplication restriction.
Use for apps and servers using these APIs:
3 For mobile applications, consider usingthe nativePlaces SDK for Androidand Places SDK for iOS.
Android apps
For apps on Android, use the Android apps application restriction.Use for apps and servers using these SDKs:
In addition, prevent accidentally checking API keys into version control byusing the Secrets GradlePlugin to inject secretsfrom a local file rather than storing them in the Android Manifest.
iOS apps
For apps on iOS, use the iOS apps application restriction.Use for apps and servers using these SDKs:
As an enthusiast with in-depth knowledge of Google Maps Platform APIs and SDKs, I want to emphasize the critical importance of implementing robust security measures to protect against unauthorized use and potential charges. The provided article offers comprehensive guidance on best practices for securing and managing API keys, with a focus on different aspects of Google Maps Platform usage.
Here's a breakdown of the key concepts discussed in the article:
-
API Key Security Best Practices:
-
Restrict Your API Keys:
- Use separate API keys for each app.
- Delete unused API keys to minimize potential vulnerabilities.
- Regularly check and monitor your API key usage.
-
API Key Restrictions:
- Apply both application and API key restrictions for increased security.
- Application Restrictions:
- Limit API key usage to specific platforms (Android, iOS, websites, or IP addresses).
- API Restrictions:
- Specify which Google Maps Platform APIs, SDKs, or services your API key can access.
-
Restricting API Keys:
- Open the Google Cloud Console.
- Select the API key you want to restrict.
- Set application restrictions (platforms, referrer websites, IP addresses).
- Set API restrictions based on the desired Google Maps Platform services.
-
-
Checking API Key Usage:
- Use the Metrics Explorer in the Google Cloud Console to:
- Identify which APIs are using your API keys.
- Choose the correct type of application restriction based on platform_type.
- Determine if your API key is only used for Google Maps Platform services.
- Use the Metrics Explorer in the Google Cloud Console to:
-
Applying Recommended API Key Restrictions:
- Follow recommendations provided by the Google Cloud Console for specific API key restrictions.
- Considerations for not seeing recommendations or incomplete ones are discussed.
-
Handling Rejected Applications:
- If an app or website is rejected after applying restrictions, check the API response error message.
- Use debugging tools for client-side SDKs (Maps JavaScript API, Android, iOS) to identify and resolve issues.
- Document and remove unnecessary application or API restrictions.
-
Deleting and Regenerating API Keys:
- Before deleting or regenerating API keys, ensure they are not used in production.
- Delete unused API keys from the Google Cloud Console.
- Exercise caution when regenerating keys, and follow recommended steps to avoid service interruptions.
-
Migrating to Multiple API Keys:
- Migrate from using one API key for multiple apps to a unique API key for each app.
- Identify apps that need new keys, create and restrict new keys, and gradually update apps.
-
Protecting Apps using Static Web APIs:
- Use digital signatures in addition to API keys for increased security.
- Implement best practices for protecting API signing secrets.
- Use secure keystore or proxy server for mobile apps using web services or Static Web APIs.
-
Handling Unauthorized Use of API Keys:
- Restrict keys and migrate to multiple keys if unauthorized use is detected.
- Document current restrictions and temporarily remove them for investigation.
- Contact support for further assistance if needed.
This article serves as a comprehensive guide for developers and businesses using Google Maps Platform APIs, providing detailed insights into security practices, key restrictions, and recommended actions for maintaining a secure and efficient mapping experience.
