Work with optimization entities

Cloud Fleet Routing provides Data-Driven APIs that enable you to create and persist the following optimization entities:

• Workspace: A top-level resource that serves as the logical container for all optimization entities. Every optimization starts with creating a workspace first.
• Shipment: A resource that describes the locations to be visited (if there are any), time windows for the visits, and items to be picked up or delivered.
• Vehicle: A resource that describes the available vehicles for the optimization.
• Optimizer: A resource that runs the optimization according to a certain specification with selected shipments and vehicles.
• Solution: A resource that contains the generated routes from the optimizer.

You can also update or delete the optimization entities to reflect the real-world change, which is then picked up by the optimizer when generating the new solution.

Run a data-driven optimization

The following example shows a basic workflow to run a data-driven optimization.

Before you begin

1. To send requests to the API using the Python client, download the Cloud Fleet Routing Python client from Cloud Storage. To do so, enter the following command:

   gcloud storage cp gs://api-client-staging/cloudoptimization-python-v1-preview-20230214.tar.gz SAVE_TO_LOCATION
   

2. Install pip, which is the Python package installer.

   sudo apt-get install python-pip
   

3. Create a virtual environment. This is where the package is installed.

   python3 -m venv tutorial-env
   

4. Activate the virtual environment.

   • If you are using bash on Unix or macOS, run:

     source tutorial-env/bin/activate
     

   • If you are using the fish shell, run:

     source tutorial-env/bin/activate.fish
     

   • If you are using the csh shell, run:

     source tutorial-env/bin/activate.csh
     

5. Install the Cloud Fleet Routing Python client library.

   pip install ./DIRECTORY_TO_THE_PACKAGE/cloudoptimization-python-v1-preview-20230214.tar.gz
   

A basic workflow example

Note: All the requests in the following examples are for demonstration purposes only. Refer to the Reference for available methods and fields. For REST examples, replace the variables with their true values. For example, replace YOUR_PROJECT_ID with your project ID.

A workspace is the top-level container to organize your resources. Create a workspace before doing anything else.

REST

#!/bin/bash
curl -X POST \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"displayName":"workspace-1"}' \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_create_workspace():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.CreateWorkspaceRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.create_workspace(request=request)

    # Handle the response
    print(response)

Create a vehicle in your workspace.

REST

#!/bin/bash
curl -X POST \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"startLocation":{"latitude":37.405268056557034,"longitude":-122.02057849549489},"endLocation":{"latitude":37.405268056557034,"longitude":-122.02057849549489},"loadLimits":{"weight":{"maxLoad":"100"}},"displayName":"vehicle_1"}' \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/vehicles"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_create_vehicle():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.CreateVehicleRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.create_vehicle(request=request)

    # Handle the response
    print(response)

Create a shipment in your workspace.

REST

#!/bin/bash
curl -X POST \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"pickups":[{"arrivalLocation":{"latitude":37.42376807113943,"longitude":-122.08044232493486},"timeWindows":[{"startTime":"2022-08-02T08:00:00Z","endTime":"2022-08-02T08:30:00Z"}],"duration":"300s"}],"deliveries":[{"arrivalLocation":{"latitude":37.51635149414521,"longitude":-122.03173566402883},"timeWindows":[{"startTime":"2022-08-02T13:30:00Z","endTime":"2022-08-02T15:00:00Z"}],"duration":"300s"}],"loadDemands":{"weight":{"amount":"20"}},"displayName":"shipment_1"}' \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/shipments"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_create_shipment():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.CreateShipmentRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.create_shipment(request=request)

    # Handle the response
    print(response)

Create an optimizer in your workspace.

REST

#!/bin/bash
curl -X POST \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"displayName":"Optimizer_1","modelSpec":{"globalStartTime":"2022-08-01T08:30:00Z","globalEndTime":"2022-08-05T08:30:00Z"},"optimizeToursSpec":{"timeout":"20s"}}' \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/optimizers"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_create_optimizer():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.CreateOptimizerRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.create_optimizer(request=request)

    # Handle the response
    print(response)

With the vehicle, shipment, and optimizer created, run the optimizer in the workspace. The response is a long-running operation.

REST

#!/bin/bash
curl -X POST \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/optimizers/{YOUR_OPTIMIZER_ID}:run"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_run_optimizer():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.RunOptimizerRequest(
        name="name_value",
    )

    # Make the request
    operation = client.run_optimizer(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

The response field in the long-running operation gives you the solution id, which is used to retrieve the solution.

REST

#!/bin/bash
curl \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/solutions/{YOUR_SOLUTION_ID}"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_get_solution():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.GetSolutionRequest(
        name="name_value",
    )

    # Make the request
    response = client.get_solution(request=request)

    # Handle the response
    print(response)

More complex workflows

Resources that you create can be updated and deleted. For example, you can update a vehicle's route information. For more information, see Perform Continuous Optimization.

REST

#!/bin/bash
curl -X PATCH \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"displayName":"vehicle_1","routeCommitments":{"routeStartTime":"2022-08-02T07:51:00Z","nextVisits":[{"shipmentName":"projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/shipments/{YOUR_SHIPMENT_ID}","isPickup":true,"startTime":"2022-08-02T08:00:00Z"}]}}' \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/vehicles/{YOUR_VEHICLE_ID}"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_update_vehicle():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.UpdateVehicleRequest(
    )

    # Make the request
    response = client.update_vehicle(request=request)

    # Handle the response
    print(response)

You can also delete created resources. For example, you can remove a shipment.

REST

#!/bin/bash
curl -X DELETE \
-H "Authorization: Bearer ""$(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://cloudoptimization.googleapis.com/v1/projects/{YOUR_PROJECT_ID}/locations/us-central1/workspaces/{YOUR_WORKSPACE_ID}/shipments/{YOUR_SHIPMENT_ID}"

Python

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import optimization_v1


def sample_delete_shipment():
    # Create a client
    client = optimization_v1.StatefulFleetRoutingClient()

    # Initialize request argument(s)
    request = optimization_v1.DeleteShipmentRequest(
        name="name_value",
    )

    # Make the request
    client.delete_shipment(request=request)

For all methods available for each resource, see the Reference.