Set up the Roads API

Page Summary

• Google Maps Platform products are secured using API keys, which are unique alphanumeric strings linked to your billing account and project.

• You can create and manage API keys through the Google Cloud Console or the Cloud SDK.

• To enhance security, restrict your API keys by limiting their usage to specific APIs and IP addresses.

• Include your API key in every Roads API request using the key= parameter within the URL.

European Economic Area (EEA) developers

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

This document describes the steps you need to start using the Roads API.

Prerequisites

This procedure guides you through setting up a Google Cloud Account and Google Cloud project with billing enabled. You should also be familiar with how you are charged for using the Roads API.

1. Review billing and cost for usage at Roads API Usage and Billing.

2. Verify that you have a Google Cloud Account.

   Sign in to the Google Cloud console
   Note: If you are a new user and don't have a Google Cloud Account, meaning you cannot sign in to the console, see Getting started with Google Maps Platform.

3. Verify that you have a Google Cloud project with billing enabled.

   Go to the Billing page
   Note: If you are a new user and don't have a Google Cloud project, see Getting started with Google Maps Platform.
1. Select your project to open the Billing page.

2. On the Billing page:

   • If billing is already enabled for the selected project, and you only have a single billing account, then the Billing page opens.
   • If you have multiple billing accounts, select Go to linked billing account to see the details about the billing account associated with the project.
   • If a billing account exists but is not associated with the project, you are prompted to link a billing account with the project.
   • If no billing account exists, or you want to create a new billing a account, select Manage Billing Accounts to create a new billing account. For more information, see Create a new self-serve Cloud Billing account.

Enable the API

Before you can use Roads API, you must use the Google Cloud console or the gcloud command to enable it in your Google Cloud project.

Note: After you enable an API you might have to wait a few minutes before you can make a request to it.

To enable the API:

Console

1. Open the product page in the Google Cloud console:

   Enable the Roads API

2. Click the Enable button.

   Note: If the API is already enabled, you see the Manage button instead of Enable.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "roads.googleapis.com"

Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

• gcloud services enable
• gcloud services disable

Get an API key for use with Roads API

Google Maps Platform products are secured from unauthorized use by requiring API calls to include an API key.

An API key is a unique alphanumeric string that associates your Cloud Billing account and Google Cloud project with the request your application makes to a Google Maps Platform API or SDK. 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

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 Roads 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 Roads API.
     3. Click Save.

   Selecting an API here doesn't enable it. Make sure Roads API is enabled on its API Library page.

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 and Add 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.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=roads.googleapis.com

  Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

  • gcloud 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.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=roads.googleapis.com

  Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

  • gcloud services api-keys update
  • gcloud 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".

Make an API request

Make a Roads API request to return a JSON response that snaps the specified points to the road geometry. You must include your API key's alphanumeric string with every request and use HTTPS for requests that include the API key.

1. Click API_KEY in the code below to insert the key's alphanumeric string:

   curl -L -X GET 'https://roads.googleapis.com/v1/snapToRoads?path=-35.27801%2C149.12958%7C-35.28032%2C149.12907%7C-35.28099%2C149.12929%7C-35.28144%2C149.12984%7C-35.28194%2C149.13003%7C-35.28282%2C149.12956%7C-35.28302%2C149.12881%7C-35.28473%2C149.12836&interpolate=true&key=YOUR_API_KEY'
   

2. Click the copy icon in the code sample, , to copy the curl command.
3. Paste the command in a terminal window and run the command.

The response is a JSON object in the form:

{
  "snappedPoints": [
    {
      "location": {
        "latitude": -35.278004899930188,
        "longitude": 149.129531998742
      },
      "originalIndex": 0,
      "placeId": "ChIJr_xl0GdNFmsRsUtUbW7qABM"
    },
    {
      "location": {
        "latitude": -35.2784195,
        "longitude": 149.12946589999999
      },
      "placeId": "ChIJr_xl0GdNFmsRsUtUbW7qABM"
    },
    ...
    {
      "location": {
        "latitude": -35.284727644851415,
        "longitude": 149.12833853807396
      },
      "originalIndex": 7,
      "placeId": "ChIJtWxAZmpNFmsRlbUCkc6VtnA"
    }
  ]
}

Apply API key restrictions

Caution: An unrestricted API key can be used to make a request to any Google Maps Platform service, including the Roads API. You are financially responsible for charges caused by abuse of unrestricted API keys.

Google strongly recommends that you restrict your API keys by limiting their usage to only the APIs and apps that need them. Restricting API keys adds security to your application by protecting it from unwarranted requests. API keys support two types of restrictions:

• API restrictions specify which SDKs and APIs can be called using the API key. The console and the gcloud CLI require at least one API restriction when you create a key.
• Application restrictions specify which websites, IP addresses, or apps can use an API key.

For more information about applying restrictions, see Restrict your API keys.

What's next

Now that you have enabled Roads API and made a successful request, see Snap to Roads to learn more about using the API.