Choose an endpoint

The Route Optimization API has the following endpoints:

The endpoint you choose depends on your use case, request size, expected solve time, and whether you need to process multiple requests simultaneously.

Compare endpoints

Use the following table to identify the right endpoint for your needs:

Endpoint OptimizeTours OptimizeToursLongRunning OptimizeToursUri BatchOptimizeTours
Execution type Blocking Non-blocking Non-blocking Non-blocking
Requests processed Single Single Single Multiple
Maximum request size Small Medium Large Large
Solve time Short Long Long Long
Requires Google Cloud Storage No No Yes Yes

Understand the endpoint characteristics

The previous table lists the following characteristics to help you choose the right endpoint:

  • Execution type: Determines how your application handles the network connection while waiting for a response. There are two types:
    • Blocking endpoints: Keep the connection open until the API returns a response.
    • Non-blocking endpoints: Process requests in the background. The API immediately returns a Long-Running Operation (LRO) ID that you poll later to retrieve results.
  • Requests processed: Determines whether the endpoint handles a single routing request, or processes multiple requests simultaneously.
  • Maximum request size: Small and medium requests are sent directly inline and have server-side limits. Large requests bypass these limits by using Google Cloud Storage. Find the exact request size limits in the endpoints details sections.
  • Solve time: Simple requests can solve in a short time, while complex requests take longer to solve. Because solve time dictates how long a connection must stay open, your endpoint choice depends on your timeout limits. For more information, see Configure timeouts and deadlines.
  • Requires Google Cloud Storage: Endpoints that process large requests and responses read and write data directly to Google Cloud Storage. Instead of sending the data in the HTTP request, you upload your request to a Cloud Storage bucket and pass the URI to the API.

Endpoint details

The Route Optimization API has four endpoints. The following sections explain how each endpoint works and include an example request.

OptimizeTours

OptimizeTours is a blocking endpoint intended for single requests with short solve times. It returns an optimized route directly in the response. Because it's a blocking endpoint, you must keep your network connection open until the API finishes processing the request for it to return a response. This endpoint accepts inline requests up to approximately 4MB.

See an OptimizeTours example request

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ],
        "deliveries":[
          {
            "arrivalLocation": {
              "latitude": 37.424215,
              "longitude": -122.095260
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}

OptimizeToursLongRunning

OptimizeToursLongRunning is a non-blocking endpoint for single requests with long solve times. It returns a Long-Running Operation (LRO) ID. You can poll this ID using the GetOperation endpoint to check the request status and retrieve the final optimized routes. This endpoint accepts inline requests up to approximately 8MB.

See an OptimizeToursLongRunning example request

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}

OptimizeToursUri

OptimizeToursUri is a non-blocking endpoint intended for single requests with long solve times and large data requirements (over 8MB). It returns a Long-Running Operation (LRO) ID. You can poll this ID using the GetOperation endpoint to check the request status.

Instead of sending your payload inline, you upload your OptimizeToursRequest to Google Cloud Storage. You then pass the Cloud Storage URIs for both your input request and your output destination to the API. The server reads the data from your input URI and writes the final OptimizeToursResponse directly to your output URI. You can read the optimized routes from this output URI once the operation is complete.

See an OptimizeToursUri example request

{
  "input": {
    "uri": "gs://your-bucket/path/input/object.json"
  },
  "output": {
    "uri": "gs://your-bucket/path/output/object.json"
  }
}

BatchOptimizeTours

BatchOptimizeTours is a non-blocking endpoint intended for multiple, independent optimization requests processed simultaneously. It returns a Long-Running Operation (LRO) ID. You can poll this ID using the GetOperation endpoint to check the request status and retrieve the final optimized routes.

Instead of sending your payload inline, you upload multiple OptimizeToursRequest to Google Cloud Storage. You then pass the Cloud Storage URIs to the API. The server reads the data from your input URIs and writes a OptimizeToursResponse for each request directly to your output URIs.

See a BatchOptimizeTours example request

{
  "modelConfigs": [
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_1.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_1.json"
        },
        "dataFormat": "JSON"
      }
    },
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_2.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_2.json"
        },
        "dataFormat": "JSON"
      }
    }
  ]
}