This page describes how to create routes and add custom attributes using the Roads Selection API in the following sections: - **[Create a route](https://developers.google.com/maps/documentation/roads-management-insights/roads-selection/create.md.txt#create)** : Define a single route using the `create` endpoint. - **[Batch create routes](https://developers.google.com/maps/documentation/roads-management-insights/roads-selection/create.md.txt#batch)** : Define multiple routes in a single request using the `batchCreate` endpoint. - **[Create a route with intermediate waypoints](https://developers.google.com/maps/documentation/roads-management-insights/roads-selection/create.md.txt#intermediates)**: Define a route with up to 25 intermediate waypoints. - **[Utilize custom route attributes](https://developers.google.com/maps/documentation/roads-management-insights/roads-selection/create.md.txt#custom)**: Add up to 10 custom key-value pairs to your routes for organizational purposes. ## Create a route To create a route, send a `POST` request to the [`create`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt) endpoint. ```html 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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) resource. This object specifies the following information: - A [`dynamicRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute) object with the following information: - The [`origin`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute.FIELDS.origin) of the selected route. - The [`destination`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute.FIELDS.destination) of the selected route. - Any [`intermediates`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute.FIELDS.intermediates), also known as waypoints, of the route. - A unique [`selectedRouteId`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt#body.selected_route_id). This value should be 4-63 characters, and valid characters are `a-z`, `A-Z`, `0-9`, `-`, or `_`. If an ID is not provided, the system generates a unique ID for the selected route. > [!WARNING] > **Warning:** The [`selectedRouteId`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt#body.selected_route_id) doesn't support any other special characters. If you add an unsupported character to your [`selectedRouteId`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt#body.selected_route_id), the API returns an `INVALID_ARGUMENT` error. ### Create a fixed route (default) Routes are created as fixed routes by default and stay consistent with the static route geometry (exported to the [`routes_status`](https://developers.google.com/maps/documentation/roads-management-insights/accumulated-data.md.txt#routes_status_table) BigQuery table) calculated at creation time without live traffic. This ensures consistent traffic data monitoring without being affected by traffic condition changes. You can set the [`dynamicRouting`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.dynamic_routing) boolean field in the request body to specify whether the route is fixed (`false`, the default) or dynamic (`true`). The following code sample shows the structure of a `POST` request to [`create`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt) a fixed route. ``` curl -X POST -d ' { "dynamicRoute": { "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" ``` > [!NOTE] > **Note:** For fixed routes, the [`dynamicRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute) field is still required to specify the `origin`, `destination`, and optional `intermediates` waypoints. On success, the API returns the [`SelectedRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) resource. The response includes the [`selectedRouteId`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt#body.selected_route_id) in the `name` field. You can use this [`selectedRouteId`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt#body.selected_route_id) to retrieve or delete the [`SelectedRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) resource. The following code sample shows the structure of a successful [`create`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt) 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", "dynamicRouting": false } ``` > [!WARNING] > **Warning:** While fixed routes remain consistent across minor road network updates, significant physical changes (such as road removal or displacement) might still cause route deviations. The auxiliary fields in the BigQuery [`routes_status`](https://developers.google.com/maps/documentation/roads-management-insights/accumulated-data.md.txt#routes_status_table) table can help detect these structural changes. ### Create a dynamic route Optionally, you can create a dynamic route by setting the [`dynamicRouting`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.dynamic_routing) field to `true`. The route geometry can change due to varying traffic conditions because Google's routing platform finds the best route every time. The following code sample shows the structure of a `POST` request to [`create`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt) a dynamic route: ``` curl -X POST -d ' { "dynamicRoute": { "origin": { "latitude": ORIGIN_LATITUDE, "longitude": ORIGIN_LONGITUDE }, "destination": { "latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE } }, "dynamicRouting": true }' \ -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" ``` The following code sample shows the structure of a successful [`create`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/create.md.txt) 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", "dynamicRouting": true } ``` ## Create a route with intermediate waypoints To create a route that passes through specific points between the origin and destination, include an [`intermediates`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute.FIELDS.intermediates) array within the [`dynamicRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute) object in your request body. Each element in the [`intermediates`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#DynamicRoute.FIELDS.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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) with intermediate waypoints: ``` curl -X POST -d ' { "dynamicRoute": { "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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) object includes a `routeAttributes` field. Use the [`routeAttributes`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.route_attributes) field to define your own custom properties for individual routes, where each attribute is a key-value pair. You can provide up to 25 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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.route_attributes) 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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.route_attributes) 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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) with custom [`routeAttributes`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute.FIELDS.route_attributes). ``` curl -X POST -d ' { "dynamicRoute": { "origin": { "latitude": ORIGIN_LATITUDE, "longitude": ORIGIN_LONGITUDE }, "destination": { "latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE } }, "routeAttributes": { "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" ``` ## Batch create routes To create multiple routes in a single request, use the [`batchCreate`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt) endpoint. This endpoint lets you define up to 1000 routes in one call. Send a `POST` request to the [`batchCreate`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt) endpoint: ```html 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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt#body.request_body.FIELDS.requests) array. Each object within this array is a [`CreateSelectedRouteRequest`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt#CreateSelectedRouteRequest) that defines an individual [`SelectedRoute`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) resource. The following code sample shows the structure of a `POST` request to the [`batchCreate`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt) endpoint: ``` curl -X POST -d ' { "requests": [ { "selectedRoute": { "dynamicRoute": { "origin": { "latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1 }, "destination": { "latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1 } } }, "selectedRouteId": "route-one" }, { "selectedRoute": { "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`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes.md.txt#SelectedRoute) resources that were created. The following code sample shows the structure of a [`batchCreate`](https://developers.google.com/maps/documentation/roads-management-insights/reference/rest/v1/selection.v1.projects.selectedRoutes/batchCreate.md.txt) 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", "dynamicRouting": false }, { "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 } }, "createTime": "CREATE_TIME_2", "state": "STATE_VALIDATING", "dynamicRouting": false } ] } ```