Understand route validation

After you create a route, the Roads Selection API performs a validation process. This validation ensures that the route is suitable for data collection and updates within Roads Management Insights. The process typically completes within a few minutes.

You can monitor the validation status of your routes through the state field in the API response. You can check this by using the get endpoint, as described in Get Selected Routes, or by examining the routes_status table in BigQuery.

Route states

The state field in a SelectedRoute resource indicates its current validation and operational status. The state field can have the following values:

  • STATE_UNSPECIFIED: The validation state of this route is not set.
  • STATE_VALIDATING: The route is being validated.
  • STATE_RUNNING: The route has successfully passed validation and is now active. The API is actively collecting data and sending periodic updates for this route to BigQuery, Pub/Sub, or both.
  • STATE_DELETING: The route has been marked for deletion and is being removed from the system.
  • STATE_INVALID: The route failed validation based on specific criteria. When a route is in STATE_INVALID, the response includes a validationError field with details on why the validation failed.

Validation errors

When a SelectedRoute resource's state is STATE_INVALID, the API response includes a validationError field. This field provides a specific reason for the validation failure.

The validationError field can have the following values:

  • VALIDATION_ERROR_UNSPECIFIED: The validation error for this route is not set.
  • VALIDATION_ERROR_ROUTE_OUTSIDE_JURISDICTION: The route is outside the authorized jurisdiction of your project.
  • VALIDATION_ERROR_LOW_ROAD_USAGE: The route has low road usage, meaning insufficient traffic data can be collected for meaningful analysis. A route classified as invalid due to low road usage may become valid again if traffic volume increases above a predetermined threshold. Learn more in Low road usage route.

Low road usage route

Routes might be flagged with VALIDATION_ERROR_LOW_ROAD_USAGE if the API determines there isn't enough traffic data for consistent analysis. This can happen during initial validation or during ongoing evaluations.

Here's what to expect for routes with low road usage:

  • Data publication to BigQuery continues: Even if a route is classified as STATE_INVALID due to low road usage, the API continues to process and publish any available data for that route to BigQuery.
  • Pub/Sub updates stop: Periodic real-time updates to Pub/Sub cease if the route's state changes to STATE_INVALID.
  • Quarterly evaluations: The API performs quarterly evaluations of all active routes for traffic volume.
    • If low traffic is detected during an evaluation, the API issues a warning within the SelectedRoute resource.
    • If low traffic persists for four consecutive quarters, the route's state changes to STATE_INVALID, and Pub/Sub updates stop.
  • Revalidation is possible: Even if a route is STATE_INVALID, it remains subject to ongoing traffic evaluations. Subsequent evaluations may reclassify the route as valid (STATE_RUNNING) if its traffic volume increases above a predetermined threshold.
  • Monitoring status: You can monitor a route's validation status through the get endpoint, as described in Get Selected Routes, or by examining the routes_status table in BigQuery.

Troubleshooting invalid routes

If your route state is STATE_INVALID, follow the next troubleshooting guidelines based on the validationError you receive:

  • VALIDATION_ERROR_ROUTE_OUTSIDE_JURISDICTION: This error indicates that the defined route extends beyond the geographic area authorized for your project. To fix this, delete the existing route and re-create the route, ensuring all its points (origin, destination, and any intermediates) are within your authorized project's jurisdiction.

  • VALIDATION_ERROR_LOW_ROAD_USAGE: This error means the selected route does not have sufficient road usage data for meaningful analysis and updates. To fix this, delete the existing route and re-create the route, selecting an area with higher road usage or "busyness" for data collection. Note that if your route has this error, the route's status can change back to STATE_RUNNING if traffic increases over time as described in Low road usage route.