Create selected routes

This page describes how to create routes and add custom attributes using the Roads Selection API in the following sections:

Create a route

To create a route, send a POST request to the create endpoint.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

The request body must be a JSON object that defines the SelectedRoute resource. This object specifies the following information:

  • A dynamicRoute object with the following information:
  • A unique selectedRouteId. This value must be between 4 to 63 characters long and only use alphanumeric characters. If you don't provide an ID, the system generates a unique ID for the selected route.

The following code sample shows the structure of a POST request to the create endpoint.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

On success, the API returns the SelectedRoute resource. The response includes the selectedRouteId in the name field. You can use this selectedRouteId to retrieve or delete the SelectedRoute resource.

The following code sample shows the structure of a successful create endpoint response.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Batch create routes

To create multiple routes in a single request, use the batchCreate endpoint. This endpoint lets you define up to 1000 routes in one call.

Send a POST request to the batchCreate endpoint:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

The URL uses gRPC Transcoding syntax.

The request body must be a JSON object containing a requests array. Each object within this array is a CreateSelectedRouteRequest that defines an individual SelectedRoute resource.

The following code sample shows the structure of a POST request to the batchCreate endpoint:

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

On success, the API returns a response containing an array of the SelectedRoute resources that were created.

The following code sample shows the structure of a batchCreate endpoint response:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Create a route with intermediate waypoints

To create a route that passes through specific points between the origin and destination, include an intermediates array within the dynamicRoute object in your request body. Each element in the intermediates array is a waypoint defined by its latitude and longitude, a route can have up to 25 waypoints.

The following code sample shows how to create a SelectedRoute with intermediate waypoints:

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Utilize custom route attributes

To enhance your route management and data analysis within Roads Management Insights, the SelectedRoute object includes a route_attributes field.

Use the routeAttributes field to define your own custom properties for individual routes, where each attribute is a key-value pair. You can provide up to 10 custom key-value pairs per route.

These attributes are useful for identifying specific routes or for grouping routes based on criteria relevant to your needs.

The following are some examples of route attributes you could use:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

Follow the next guidelines when defining the routeAttributes field:

  • Keys must not begin with the prefix goog.
  • The length of each key and each value must not exceed 100 characters.

You can then use these custom routeAttributes within Roads Management Insights in the following ways:

  • Filter Pub/Sub notifications: You can set filters on your Pub/Sub subscriptions to receive updates only for routes that match or don't match specific attribute keys and their corresponding values.
  • Refine BigQuery analysis: In your BigQuery tables, you can use these attributes to filter for specific routes based on an attribute's value. You can also group routes by a specific attribute key for more targeted data analysis.

The next code sample shows how to create a SelectedRoute with custom routeAttributes.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"