This document describes the steps you need to start using the Route Optimization 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 Route Optimization API. 1. **Review** billing and cost for usage at [Route Optimization API Usage and Billing](https://developers.google.com/maps/documentation/route-optimization/usage-and-billing.md.txt). 2. **Verify** that you have a [Google Cloud Account](https://support.google.com/accounts/answer/15277265). [Sign in to the Google Cloud console](https://console.cloud.google.com/google/maps-apis/overview?utm_source=Docs_SignIn&utm_content=Docs_routeoptimization&ref=/maps/documentation/route-optimization/get-api-key) > [!NOTE] > **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](https://developers.google.com/maps/get-started.md.txt). 3. **Verify** that you have a [Google Cloud project](https://cloud.google.com/apis/docs/getting-started#creating_a_google_project) with billing enabled. [Go to the Billing page](https://console.cloud.google.com/projectselector/billing?utm_source=Docs_Billing&utm_content=Docs_routeoptimization&ref=/maps/documentation/route-optimization/get-api-key) > [!NOTE] > **Note:** If you are a new user and don't have a Google Cloud project, see [Getting started with Google Maps Platform](https://developers.google.com/maps/get-started.md.txt). 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](https://cloud.google.com/billing/docs/how-to/create-billing-account). ## Enable the API Before you can use Route Optimization API, you must use the Google Cloud console or the [`gcloud`](https://cloud.google.com/sdk) command to enable it in your Google Cloud project. > [!NOTE] > **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 Route Optimization API](https://console.cloud.google.com/apis/library/routeoptimization.googleapis.com?utm_source=Docs_EnableAPIs&utm_content=Docs_routeoptimization&ref=/maps/documentation/route-optimization/get-api-key) 2. Click the **Enable** button. > [!NOTE] > **Note:** If the API is already enabled, you see the **Manage** button instead of **Enable**. ### gcloud ```bash gcloud services enable \ --project "PROJECT" \ "routeoptimization.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 enable`](https://cloud.google.com/sdk/gcloud/reference/services/enable) - [`gcloud services disable`](https://cloud.google.com/sdk/gcloud/reference/services/disable) Google Maps Platform products require API calls to include an OAuth token to prevent unauthorized use. ## Create an OAuth token Route Optimization API supports OAuth 2.0 for authentication. Google supports common OAuth 2.0 scenarios, such as scenarios for a web server. This document describes how to pass an OAuth token to a Route Optimization API call in your development environment. For more information about using OAuth in a production environment, see [Authentication methods at Google](https://cloud.google.com/docs/authentication). You can call Google Maps APIs directly by making API requests to the server, or you can use [client libraries](https://cloud.google.com/apis/docs/client-libraries-explained) to simplify your code. Google Maps provides client libraries for Go, Java, Node.js, and Python. For more information, see [Route Optimization API client libraries](https://developers.google.com/maps/documentation/route-optimization/client-libraries.md.txt). ## OAuth overview You can create and manage access tokens with OAuth in several ways depending on your deployment environment. You can use OAuth 2.0 for server-to-server interactions between your application and a Google service. For this scenario, you use a service account that's associated with your application rather than an individual user. You can make API requests using the service account without involving users directly. For more information about authentication methods, see [Authentication methods at Google](https://cloud.google.com/docs/authentication). Alternatively, you can integrate Route Optimization API into an Android or iOS mobile app. For more information about using OAuth and managing access tokens for different deployment environments, see [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2.md.txt). ## OAuth scopes To use OAuth with Route Optimization API, you must assign the OAuth token the following scope: https://www.googleapis.com/auth/cloud-platform ## Configure roles This document provides information on Identity and Access Management (IAM) roles and permissions for Route Optimization. IAM lets you grant granular access to specific Route Optimization resources and helps prevent access to other resources. IAM lets you apply the security principle of least privilege, which states that no one should have more permissions than they actually need. When a principal (a user, group, or service account) calls a Google Cloud API, that principal must have the appropriate IAM permissions to use the resource. To give a principal the required permissions, you grant an IAM role to the principal. To familiarize yourself with managing access in Google Cloud in general, see [IAM overview](https://cloud.google.com/iam/docs/overview). The predefined IAM roles to allow principals to access Route Optimization are: - `Route Optimization Editor (roles/routeoptimization.editor)`: grants the user or services account read and write access to Route Optimization resources in the project. This includes the ability to call `OptimizeTours` and `BatchOptimizeTours`, as well as to retrieve long running operations using `GetOperation`. - `Route Optimization Viewer (roles/routeoptimization.viewer)`: grants read-only access to Route Optimization resources in the project. This role enables the ability to call `OptimizeTours` and access to Long Running Operations using `GetOperation`. You can assign a role by creating binding for a principal using the Cloud SDK: ```go gcloud projects add-iam-policy-binding PROJECT \ --member user:someone@example.com \ --role roles/routeoptimization.editor ``` For more information, see [Grant an IAM role by using the Google Cloud console](https://cloud.google.com/iam/docs/grant-role-console). ## Example: Try REST API calls in your local development environment If you don't have an environment that generates tokens and you want to try Route Optimization API with an OAuth token, use the procedure in this section. This example describes how to use the OAuth token provided by [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) to make the call. For more information about using ADC to call Google APIs with client libraries, see [Authenticate using client libraries](https://cloud.google.com/docs/authentication/client-libraries). Use the following REST procedure only for development or testing, not for production. ### Prerequisites Before you make a REST request using ADC, use the `gcloud` CLI to provide credentials to ADC: 1. Install and initialize the `gcloud` CLI. For more information, see [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install). 2. Authenticate with the `gcloud` CLI: ``` gcloud auth application-default login ``` 3. Complete the sign-in process to save your credentials in the [local credential file used by ADC](https://cloud.google.com/docs/authentication/application-default-credentials#personal). For more information, see [Set up ADC for a local development environment](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment). ### Make a REST request In this example, you pass two request headers: - Pass the OAuth token in the `Authorization` header by using the following command to generate the token: [`gcloud auth application-default print-access-token`](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token) The returned token has a scope of `https://www.googleapis.com/auth/cloud-platform`. - Pass the ID or name of your Google Cloud project that has billing enabled in the `X-Goog-User-Project` header. To call Route Optimization API using an OAuth token, complete the following steps: 1. In the following code sample, replace PROJECT_NUMBER_OR_ID with your Google Cloud project number or ID: ``` curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data-binary @- << EOM { "model": { "shipments": [ { "pickups": [ { "arrivalLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.79581, "longitude": -122.4218856 } } ] } ], "vehicles": [ { "startLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 }, "endLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 } } ], "globalStartTime": "2023-01-13T16:00:00-08:00", "globalEndTime": "2023-01-14T16:00:00-08:00" } } EOM ``` 2. To copy the `curl` command, click **Copy** in the code sample. 3. Paste the command in a terminal window, and then run it. The response is a JSON object: ```json { "routes": [ { "vehicleStartTime": "2023-01-14T00:00:00Z", "vehicleEndTime": "2023-01-14T00:39:22Z", "visits": [ { "isPickup": true, "startTime": "2023-01-14T00:00:00Z", "detour": "0s" }, { "startTime": "2023-01-14T00:19:53Z", "detour": "0s" } ], "transitions": [ { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-14T00:00:00Z" }, { "travelDuration": "1193s", "travelDistanceMeters": 9007, "waitDuration": "0s", "totalDuration": "1193s", "startTime": "2023-01-14T00:00:00Z" }, { "travelDuration": "1169s", "travelDistanceMeters": 9546, "waitDuration": "0s", "totalDuration": "1169s", "startTime": "2023-01-14T00:19:53Z" } ], "metrics": { "performedShipmentCount": 1, "travelDuration": "2362s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "0s", "totalDuration": "2362s", "travelDistanceMeters": 18553 } } ], "metrics": { "aggregatedRouteMetrics": { "performedShipmentCount": 1, "travelDuration": "2362s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "0s", "totalDuration": "2362s", "travelDistanceMeters": 18553 }, "usedVehicleCount": 1, "earliestVehicleStartTime": "2023-01-14T00:00:00Z", "latestVehicleEndTime": "2023-01-14T00:39:22Z" } } ``` ### Troubleshooting If your request returns an error message stating that this API doesn't support end-user credentials, see [Troubleshoot your ADC setup](https://cloud.google.com/docs/authentication/troubleshoot-adc).