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 gRPCfor 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
timeoutparameter 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:
-
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) .
-
Define shipments.In the
shipmentsfield, add aShipmentmessage 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.-
For each dog, create a
VisitRequestfor pickups and another for the deliveries, which, for this scenario, is referred to as the daycare dropoff.-
In pickups, set the
arrivalWaypointto the dog's pickup location (Coit Tower for the Bernese mountain dog or South Sunset Playground Park for the Chihuahua) and thetimeWindowsto the owner's requested pickup time (7:30 AM to 9:30 AM). -
In deliveries, set the
arrivalWaypointto the daycare center and thetimeWindowsfor the required dropoff time (9:30 AM to 11:30 AM).
For more information on time windows, see Time windows .
-
-
You can use the
labelfield 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 .
-
-
Define vehicles.In the
vehiclesfield, add aVehiclemessage 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.-
Set the
startWaypointandendWaypointfor the van to the start and end locations of the day, which is the daycare center near Mission Dolores Park. -
To minimize your costs of operation, you must define the cost constraints of your business. Set the cost parameter
costPerHourto 27, which is how much you pay the driver for driving the doggy daycare van. For more information on cost parameters, see Cost model . -
To ensure the optimizer creates a route within the van's operational hours, define the
startTimeWindowsto the acceptable range for the driver to start operating the van andendTimeWindowsto the acceptable range for when the driver must return to the daycare center. For more information on time windows, see Time windows .
For more information on defining vehicles, see Vehicle .
-
-
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
globalStartTimeto 7:00 AM andglobalEndTimeto 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
'h
tt
ps
:
//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)"
\
--
da
ta
@
-
<<
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
}
}
},
"timeWindows"
:
[
{
"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
}
}
},
"timeWindows"
:
[
{
"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.
OptimizeToursRequest
pickups
and to the daycare center's address for deliveries
.