> [!NOTE] > This product is in [Legacy status](https://developers.google.com/maps/legacy.md.txt). As of October 2026, Distance Matrix API (Legacy) can no longer be enabled for new Google Cloud projects. Existing projects remain fully supported. For new features and improved performance, [migrate to the Routes > API](https://developers.google.com/maps/documentation/routes/migrate-routes).
Google secures Google Maps Platform products from unauthorized use by restricting API calls to those that provide proper authentication credentials. These credentials are in the form of an API key, which is a unique alphanumeric string that associates your Cloud Billing account with your project and with the specific API or SDK. This guide shows how to create, restrict, and use your API key for Google Maps Platform. ## Before you begin Before you start using the Distance Matrix API (Legacy), you need a project with a billing account and the Distance Matrix API (Legacy) enabled. To learn more, see [Set up in Cloud console](https://developers.google.com/maps/documentation/distance-matrix/cloud-setup.md.txt). ## Create API keys The API key is a unique identifier that authenticates requests associated with your project for usage and billing purposes. You must have at least one API key associated with your project. To create a new key or add an API or SDK to an existing key, follow these instructions. ### Console 1. Go to the **Google Maps Platform \> Keys \& Credentials** page. [Go to the Keys \& Credentials page](https://console.cloud.google.com/projectselector/google/maps-apis/credentials?utm_source=Docs_CreateAPIKey&utm_content=Docs_distance-matrix-backend) 2. If prompted, select your project. 3. Do one of the following: - **Create a new key**: 1. Click **Create credentials \> API key**. 2. In the **Create API key** panel, open the **Select API restrictions** list. 3. Clear any APIs that this key doesn't need, and make sure **Distance Matrix API** stays selected. 4. Click **Create**. The panel displays your new API key. - **Use an existing key**: 1. Click the name of the key. 2. In the **Select API restrictions** list, select **Distance Matrix API**. 3. Click **Save**. Selecting an API here doesn't enable it. Make sure Distance Matrix API is enabled on its [API Library page](https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com). 4. To see the key string later, go to the **Keys \& Credentials** page and click **Show key** for the key. If the console looks different from these steps, see [Create an API key](https://cloud.google.com/docs/authentication/api-keys#create) and [Add API restrictions](https://cloud.google.com/docs/authentication/api-keys#adding-api-restrictions) in the Google Cloud documentation. ### gcloud Replace PROJECT_ID with your project ID in the following commands. - **Create a new key** : Run the following command, and replace DISPLAY_NAME with a name for the key. ```bash gcloud services api-keys create \ --project="PROJECT_ID" \ --display-name="DISPLAY_NAME" \ --api-target=service=distance-matrix-backend.googleapis.com ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services api-keys create`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/create) - **Use an existing key** : Run the following command, and replace KEY_ID with the ID of the key. The `--append` flag keeps the APIs that the key already allows. Without it, the command replaces them. ```bash gcloud services api-keys update KEY_ID \ --project="PROJECT_ID" \ --append \ --api-target=service=distance-matrix-backend.googleapis.com ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services api-keys update`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/update) - [`gcloud services api-keys list`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/list) The key ID isn't the key string or display name. To find it, run `gcloud services api-keys list --project="PROJECT_ID"`. The ID is the last part of the `name` field: `projects/PROJECT_NUMBER/locations/global/keys/KEY_ID`. To see the key string, run `gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID"`. ## Restrict API keys Google strongly recommends that you restrict your API keys by limiting their usage to only the APIs needed for your application. Restricting API keys adds security to your application by protecting it from unwarranted requests. **You are financially responsible for charges caused by abuse of unrestricted API keys.** For more information, see [API security best practices](https://developers.google.com/maps/api-security-best-practices.md.txt#restricting-api-keys). > [!CAUTION] > A key's **Application restrictions** and **API restrictions** both apply. A request must come from an allowed website, IP address, or app, and it must call an allowed API. Follow best practices by creating a separate API key for each app, and for each platform on which that app is available. To restrict an API key: ### Console 1. Go to the **Google Maps Platform \> Keys \& Credentials** page. [Go to the Keys \& Credentials page](https://console.cloud.google.com/project/_/google/maps-apis/credentials?utm_source=Docs_RestrictAPIKey&utm_content=Docs_distance-matrix-backend) 2. Select the API key that you want to set a restriction on. The API key property page appears. 3. Under **Key restrictions**, set the following restrictions: - Application restrictions: 1. To accept requests from the list of web server IP addresses that you supply, select **IP addresses** under **Application restrictions** . Specify one or more IPv4 or IPv6 address, or subnet using CIDR notation. The IP addresses must match the source address the Google Maps Platform servers observe. If you use [network address translation (NAT)](https://en.wikipedia.org/wiki/Network_address_translation), this would typically correspond to your machine's *public* IP address. - API restrictions: 1. In **Select API restrictions** , make sure **Distance Matrix API** is selected. If it isn't listed, you need to [enable](https://developers.google.com/maps/documentation/distance-matrix/cloud-setup.md.txt#enabling-apis) it. 4. To finalize your changes, click **Save** . ### gcloud Run the following command. Replace KEY_ID with the ID of the key and PROJECT_ID with your project ID. To find the key ID, run `gcloud services api-keys list --project="PROJECT_ID"`. The ID is the last part of the `name` field. > [!WARNING] > **Warning:** The [`gcloud services api-keys update`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/update) command replaces the key's API restrictions and the type of application restriction that you pass. The following command uses the `--append` flag, which adds to the key's existing restrictions instead. If the key already has a different type of application restriction, the command fails. ```bash gcloud services api-keys update KEY_ID \ --project="PROJECT_ID" \ --append \ --api-target=service=distance-matrix-backend.googleapis.com \ --allowed-ips="IP_ADDRESS" ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services api-keys update`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/update) - [`gcloud services api-keys list`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/list)
## Add the API key to your request
You must include an API key with every Distance Matrix API (Legacy) request. In the following example, replace `YOUR_API_KEY` with your API key: `https://maps.googleapis.com/maps/api/distancematrix/json?origins=Seattle&destinations=San+Francisco&key=YOUR_API_KEY`
You must use HTTPS for requests that use an API key. > [!NOTE] > **Note**: When using web services, all special characters inside the parameters must be URL-encoded. URLs must be properly encoded to be valid and are limited to 2,048 characters for all web services. Be aware of this limit when constructing your URLs. Different browsers, proxies, and servers might also have different URL character limits.