## Overview

> [!WARNING]
> **Important:** In order to increase authentication security and reliability, Maps Platform client IDs are deprecated since May 26, 2025, and can no longer be used after May 31, 2026.   
> Instead of using a client ID, you must use API Key credentials to authenticate your Google Maps API service traffic. This guide shows you how to migrate from using client IDs, to using API keys.

Follow these steps to get started:

1. [Check the current client ID usage](https://developers.google.com/maps/premium/migrate-client-id.md.txt#check-current-usage)
2. [Prepare API Keys](https://developers.google.com/maps/premium/migrate-client-id.md.txt#prepare-api-keys)
3. [Review quota settings](https://developers.google.com/maps/premium/migrate-client-id.md.txt#review-quota-settings)
4. [Update your code](https://developers.google.com/maps/premium/migrate-client-id.md.txt#update-your-code)
5. [Monitor your client ID traffic](https://developers.google.com/maps/premium/migrate-client-id.md.txt#monitor-client-id-traffic)
6. [Pause your client ID](https://developers.google.com/maps/premium/migrate-client-id.md.txt#pause-client-id)
7. [Client ID self-service temporary reactivation](https://developers.google.com/maps/premium/migrate-client-id.md.txt#temporary-reactivation)

## Check current client ID usage

Before beginning the migration process, list the following:

- Maps Platform Services with which you are using with your client ID.
- Applications, sites, or systems with which you are using your client ID.

Google sent a notification email to affected customers about client ID
deprecation in May 2025. You can find this information in the notification email
as well.

On the Cloud Console, you can check the latest status of your Client ID usage
on the [Google Maps Metrics Page](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#google-maps-metrics)

**For a list of Maps Platform Services**:

1. Open the [Metrics](https://console.cloud.google.com/project/_/google/maps-apis/metrics) page on the Cloud Console.
2. Filter your usage with the following settings:
   - Credentials: Select "project_number:\<numerical identifier\>" only.
3. Set the following filter.
   - Grouped by: API

**For hints of applications, sites, or systems**:

The Cloud Console doesn't show details of your applications, sites, or systems.
But you can find some hints of sources of your Client ID traffic. Follow these
steps:

1. Open the [Metrics](https://console.cloud.google.com/project/_/google/maps-apis/metrics) page on the Cloud Console.
2. Select a Maps Platform service from the drop-down.
3. Filter your usage with the following settings:
   - Credentials: Select "project_number:\<numerical identifier\>" only.
4. Set the following filter.
   - Group by: Platform, or Domain
5. Repeat from step 2 for each Maps Platform service for which you need to check the traffic.

## Prepare API keys

All client IDs are associated with a Google Cloud project, and using an API key
from that project will give you access to the same features that you previously
accessed with your client ID. We recommend migrating to the associated project,
to avoid issues with quotas or missing features.

1. Find the Cloud Project that your client ID is linked to:
   - [Portal Migration FAQ](https://developers.google.com/maps/premium/portal-shutdown-faq.md.txt#where-client-id)
2. Make sure your Cloud Project is [linked to an open Billing Account](https://console.cloud.google.com/billing/linkedaccount).
3. [Create a new API key](https://developers.google.com/maps/get-started.md.txt#api-key) for client ID migration.
   - You can reuse any existing API keys on the Cloud Project.
   - You can use multiple API keys from the same Cloud Project, for example, in order to separate traffic for each Maps Platform service, or to separate traffic from different platforms (browser, mobile app, and so on). Refer to the [security guide](https://developers.google.com/maps/api-security-best-practices.md.txt) for best practices on API key management.

### Secure your API key

Be sure to secure your API key to protect your key from unauthorized access.

- Set an application restriction for your API key (e.g. Websites, IP addresses, Android apps, or iOS apps).
- Set API restrictions for your API key.

For more details see [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices.md.txt).

For Maps JavaScript API, Maps Static API, and Street View Static API, you can
migrate the trusted referrers on your client ID to the API key restrictions. You
can find the list of trusted referrers on the Cloud Console.

## Review quota settings

Make sure you have expected quota settings on your Cloud Project. You only need
to do this if you are calling the Maps JavaScript API client-side services from
a client ID. You can check and adjust your quota settings on the
[Google Maps Quotas Page](https://console.cloud.google.com/project/_/google/maps-apis/quotas).

[Learn more about quota reports](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#quota-rpt)

### Quota increase for Maps JavaScript API client-side services

> [!WARNING]
> **Warning:** Client ID usage on the Maps JavaScript API client-side services does not consume project quota. Once you migrate to an API key, your usage will consume project quota. You should make sure you have sufficient quota headroom before migrating.

If you are using the following services on Maps JavaScript API, you will see the
quota usage increase after the API key migration.

Review your current quota configuration, current usage, and
[adjust your quota limits accordingly](https://developers.google.com/maps/billing-and-pricing/manage-costs.md.txt#quotas).

1. Check if you are using Maps JavaScript API client-side services with a client ID.
   - Open the [Metrics](https://console.cloud.google.com/project/_/google/maps-apis/metrics) page on the Cloud Console.
   - Filter your usage with the following settings:
     - Grouped by: API Method
     - Credentials: Select "project_number:\<numerical identifier\>" only.
   - Then, you'll see a list of Method names with its traffic in the "Traffic by API Method" chart.

|---|---|---|
| **API Method** | **Client-side service** | **Service to adjust the quota** |
| google.routes.Directions.Javascript | Directions Service | Directions API |
| google.routes.DistanceMatrix.Javascript | Distance Matrix Service | Distance Matrix API |
| google.maps.Elevation.Javascript | Elevation Service | Elevation API |
| google.places.Geocoding.Javascript | Geocoding Service | Geocoding API |
| google.places.\*.Javascript, other than google.places.Geocoding.Javascript | Places Library | Places API |

- If you don't use those API methods, you don't need to worry about quota settings, as your client ID traffic already consumes your project quota.
- Estimate your client ID quota usage
  - For each of the services, check both the Per Second, and the Per Day granularity.
  - Per Second graph: multiply the peak traffic by 60 for the additional Quota Per Minute needs.
  - Per Day graph: The peak traffic should be the additional Quota per Day needs.
- Adjust your quota on the corresponding Maps Platform services
  - Based on the method name which you find in Step 1, adjust quota on the corresponding services.

## Update your code

### Replace client parameter with key parameter

Update the authentication credentials from `URL&client={value}` to
`URL&key={value}` in your outgoing GMP API calls. If your apps are using HTTP to
access GMP services, update them to use HTTPS.

### Update channel parameter for reporting

You can track your usage per channels by specifying the channel parameter to
your API requests. API keys only support numerical values for the channel
parameter. If you are using your Client ID with any non-numerical values for the
channel parameter, update it to a numerical value supported values.

See the
[Google Maps Platform Reporting](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#usage-tracking-per-channel)
for more information.

### Remove signature parameter for web services

For the following Web Service APIs, the signature parameter is not needed when
you access them with an API key. Only remove the signature parameter from your
API requests.

- Directions API (Legacy)
- Distance Matrix API (Legacy)
- Geocoding API
- Elevation API
- Time Zone API

See the [Premium Plan Overview](https://developers.google.com/maps/premium/overview.md.txt)
for more information.

### Signing Secret for Imagery APIs

Maps Static API, and Street View Static API still require the signature
parameter. They accept a small number of requests without signature for testing
purposes, but they start failing once it hits the threshold in your production.
Replace your signing secret from the one for the client ID to the one for
the API key. You can use the same signing algorithm, but you need to use another
signing secret. To learn more, see
[Use a Digital Signature](https://developers.google.com/maps/documentation/maps-static/digital-signature.md.txt).

> [!WARNING]
> **Warning:** Prior to deploying code changes to production verify that end to end functionality has not been impacted.

## Monitor your client ID traffic

After the deployment, confirm that your traffic has migrated successfully
using [the Cloud Console dashboards](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#cred-report).
You will start seeing a decrease in your client ID traffic, which is shown in
"project_number:123456" format on the dashboard when grouping by credential.

## Pause your client ID

We strongly recommend that developers pause client IDs after the migration. It
is to protect your credentials from any unintended traffic, and to confirm that
any remaining usage on your client ID is not critical (e.g. testing, caches,
bots, ...) and can return errors without causing business impact. You can pause
your client ID on the Cloud Console. See [Premium Plan Authentication Overview](https://developers.google.com/maps/premium/authentication/overview.md.txt#pause-client-id)
for more details.

## Client ID self-service temporary reactivation

As Google Maps Platform Client IDs entered the phased deprecation period in May
2026, service availability is no longer assured. Access will be periodically
restricted as part of the scheduled service termination process. While service
is typically restored automatically within a few hours, you may choose to
manually reactivate access if immediate restoration is required.

To urgently restore access, you can perform a self-service reactivation through
the Google Cloud Console:

- Navigate to the [Google Maps Platform Credentials page](https://console.cloud.google.com/project/_/google/maps-apis/credentials).
- Locate your specific Cloud Project which is linked to your Client ID.
- Click the unpause icon located at the far right of the entry to restore service.

> [!NOTE]
> **Note:** These service interruptions will increase in frequency and duration as the final termination date approaches. To ensure uninterrupted service, we strongly recommend migrating to API key authentication as soon as possible.

If you aren't able to quickly migrate to API keys and want to be temporarily
exempt from further interruptions, please contact the Google Maps Platform
Support team with the following details:

- Client ID
- Specific use case
- Target migration date
- Business impact assessment

## Client ID usage report - from Billing Reports

Checking Billing reports instead of Project Metrics can be useful for users who
don't have access to project metrics---for example, billing administrators
(especially Maps Platform Partners). While Billing Reports have a 1-2 day
latency, they have the benefit of showing more than 30 days of usage and cost
insights.

You can monitor Client ID usage through the Google Cloud Console by following
these steps:

1. Navigate to the **Billing \> Reports** page in the Google Cloud Console.
2. (Optional, relevant for Partners only) Apply a filter to select the desired sub-billing account.
3. Group the report data by the label key `goog-maps-api-key-suffix`. This label displays the trailing characters of an API key.
4. Identify Client ID traffic by looking for entries where the `goog-maps-api-key-suffix` label is missing or empty, as this label is not populated for Client ID requests.
5. Ignore SKUs which are not meant to be associated with API requests---for example, subscription SKUs.

## Troubleshooting

### How can we see if our request is failing or not?

You can check your error stats on the [Response code graphs](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#response-code-graphs)

### `ApiNotActivatedMapError`, or `REQUEST_DENIED` error

You will see the `ApiNotActivatedMapError`, or `REQUEST_DENIED` error, if you
didn't enable the service on your Cloud Project. Follow the instructions to
[enable the service](https://developers.google.com/maps/get-started.md.txt#enable-api-sdk).

### `RefererNotAllowedMapError` error

You will see the RefererNotAllowedMapError error, if your source domain is not
added to your API key. Check the "Secure your API key" section, and add
your domain to the API key.

### `OverQuotaMapError`, or `OVER_QUERY_LIMIT` error

You will see the `OverQuotaMapError`, or `OVER_QUERY_LIMIT`, if your configured
quota is not sufficient to cover your traffic. Check the "Review quota settings"
section, and adjust your quota accordingly.

### "Requests to this API must be over SSL" error

If you receive the following error message, update your API requests from
"http://" to "https://".

```json
{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}
```