Make your first Route Optimization request

This document shows you how to make your first request to the Route Optimization API using a real-world use-case scenario.

For simplicity, the example uses HTTP and JSON to demonstrate the REST API. For your production environment, however, the overall recommendation is to use gRPC for its performance benefits. However, gRPC requires some installation. For more information, see Route Optimization API client libraries.

Scenario

You run a doggy daycare service from 7:00 AM to 7:00 PM in San Francisco. This morning, you need to pick up two dogs from different locations in the city. Both dog owners gave you a pickup window between 7:30 AM and 9:30 AM.

You have one van for the job, and you pay the driver 27 dollars an hour. The driver and van start the day at your daycare center at 7:00 AM and need to be back from the morning pickups by 12:00 PM for a lunch break.

Today is February 13, 2024, and the driver has the following tasks:

• Pick up the Bernese mountain dog near Coit Tower.
• Pick up the Chihuahua at the South Sunset Playground Park.
• Drop off both dogs at the doggy daycare center at Mission Dolores Park.

You need a route that minimizes the time the dogs spend in the van, while meeting the pickup and dropoff requirements.

Before you begin

To run the code in this example scenario, you must first complete the instructions in Set up the Route Optimization API.

1. Choose your route optimization approach

The Route Optimization API has multiple methods for you to choose from depending on the complexity of your optimization problem.

Because this doggy daycare scenario is a small and straightforward request, use a blocking method, such as optimizeTours, which quickly delivers results for small requests. For more information about the Route Optimization API methods, see Synchronous and asynchronous endpoints.

Use the following URL to make an HTTP POST request to the optimizeTours method:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

You also need to set the timeout and deadline settings to be short to reduce any unnecessary wait time. For this doggy daycare scenario, the optimizer doesn't need a lot of time to respond to your request, so use the following settings:

• Set the timeout parameter to 2 seconds.
• Leave the deadline settings at the default, which is 60 seconds for REST requests.

2. Construct the request message body

After choosing the blocking optimizeTours method and defining the timeout and deadline settings, your next step is to construct the body of the request message.

For this scenario, the request is an OptimizeToursRequest message encoded as JSON in the REST API.

To construct the request message, follow the next steps:

1. Start with the basic request structure, which is as follows:

   {
     "timeout": ...,
     "model": {
       "shipments": [...],
       "vehicles": [...],
       "globalStartTime": "...",
       "globalEndTime": "..."
     }
   }
   

   For more information on the structure, see the key concept guide for Base structure (ShipmentModel, Shipment, and Vehicle).

2. Define shipments. In the shipments field, add a Shipment message for each dog that needs to be picked up and dropped off in the morning. This is where you define each of the dog owner's preferred pickup location and times and the daycare center's location and times to drop the dogs off.

   1. For each dog, create a VisitRequest for pickups and another for the deliveries, which, for this scenario, is referred to as the daycare dropoff.

      • In pickups, set the arrivalWaypoint to the dog's pickup location (Coit Tower for the Bernese mountain dog or South Sunset Playground Park for the Chihuahua) and the timeWindows to the owner's requested pickup time (7:30 AM to 9:30 AM).

      • In deliveries, set the arrivalWaypoint to the daycare center and the timeWindows for the required dropoff time (9:30 AM to 11:30 AM).

      For more information on time windows, see Time windows.

   2. You can use the label field to add an identifier for each shipment, like "Bernese mountain dog" and "Chihuahua". This can help you identify the shipments in the response.

   For more information on defining shipments, see Shipment.

3. Define vehicles. In the vehicles field, add a Vehicle message for your one van with the daycare center as the starting and end points, the cost of the driver's wage, and the operational hours for the van.

   1. Set the startWaypoint and endWaypoint for the van to the start and end locations of the day, which is the daycare center near Mission Dolores Park.

   2. To minimize your costs of operation, you must define the cost constraints of your business. Set the cost parameter costPerHour to 27, which is how much you pay the driver for driving the doggy daycare van. For more information on cost parameters, see Cost model.

   3. To ensure the optimizer creates a route within the van's operational hours, define the startTimeWindows to the acceptable range for the driver to start operating the van and endTimeWindows to the acceptable range for when the driver must return to the daycare center. For more information on time windows, see Time windows.

4. Set a global time window. The global time window represents the timeframe for when the van may perform pickups and dropoffs for your daycare throughout the day. For this scenario, set globalStartTime to 7:00 AM and globalEndTime to 7:00 PM for February 13, 2024, which represent your doggy daycare operational hours.

3. Send the request

The following is a simple curl request based on the doggy daycare scenario and uses the blocking optimizeTours method.

Before you send the request, replace PROJECT_NUMBER_OR_ID in the sample code with your Google Cloud project 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 @- << EOM
{
  "timeout": 2s,
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

Request parameters used in the request

The following table describes the request parameters used in the request body of the example scenario. You can filter the contents by parent or by text search.

Next

Interpret the responsearrow_forward