With the Roads Selection API, you can conduct road data analytics in Big Query in order to improve the safety and efficiency of road-networks and to reduce pollution.
For example:
- Analyze traffic patterns and plan infrastructural and systemic improvements to the road network.
- Analyze traffic patterns and plan for future events and emergencies.
- Monitor air pollution.
- Report externally on progress on public goals and key metrics, such as journey time reliability.
What you can do with the Roads Selection API
You use the Roads Selection API to subscribe to historical traffic data for routes you're interested in. Once you subscribe to a given route, the service periodically retrieves and publishes information for that route in a Big Query table. From there you can conduct roads data analytics with the tooling of your choice. Specially, you use the following services:
- create-selected-route: Use this service to register your interest in periodic roads data information for a route that passes through latitude/longitude coordinates you supply for origin, destination, and intermediates waypoints.
-
get-selected-route: Use this service to review the routes you have
created by supplying the
selected_route_idof the route you want to review. -
delete-selected-route: Use this service to unsubscribe from roads
traffic data for a given route by supplying the
selected_route_id. - list-selected-routes: Use this service to retrieve all the routes you have created.
- batch-create-selected-route: Use this service to register for roads data information for multiple routes. Do this by passing in the origin, destination and intermediate waypoints for each route you're interested in.
How the Roads Selection API works
The Roads Selection API accepts an HTTPS request containing latitude/longitude
coordinates that best represent the route you’re interested in analyzing. This
includes coordinates for origin, intermediate waypoints, and destination. The
following example registers a route for a street in San Francisco. It sets the
selected_route_id to sf-downtown:
curl -X POST -d '
{"dynamic_route": { origin: {latitude: -37.78 ,longitude: -122.41}, "intermediates": [
{
"latitude": -37.76,
"longitude": -122.41
},
{
"latitude": -37.75,
"longitude": -122.42
},
],
destination: {latitude: -37.74, longitude: -122.42}}}' \
-H 'X-Goog-User-Project: PROJECT_NUMBER' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
"https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=sf-downtown"The service registers the provided waypoints with the selected_route_id
provided in the request. If no selected_route_id is provided, the system
generates a unique selected_route_id for your route.
API Resources
The following table summarizes the resources available through the Roads Selection API along with the data it returns.
| Data resources | Data returned | Return format |
|---|---|---|
| Selected-Route |
A series of waypoints containing origin, destination and intermediates that best represent the route of interest. |
JSON |
Roads Data Caching
Once the selected routes are registered, it goes through the validation phase (which usually finishes within a few minutes). The status turns to STATE_RUNNING if validation passes and roads data starts caching. Or it turns to STATE_INVALID status if validation does not pass. The validation error is either caused by the selected route is outside of specified jurisdiction or it has low road usage (See route restrictions). If the validation does not pass, try to re-create routes within your jurisdiction and have enough busyness.
You can check the status for your individual selected_routes in the
routes_status table. This table is accessible under the Analytics Hub Listing
for Historical Roads Data. Data is written to this table every hour, so the
status information might be delayed by up to an hour. If you need the latest
status for a route, you can query it directly using the GetSelectedRoute API
method.
Once the route is in running status, the traffic-aware roads data (travel time, route geometry) is periodically retrieved every 2 minutes and cached internally. It is possible that the route geometry can be different because Google's routing service finds the optimal route across your input waypoints based on the traffic condition.
Roads Data Sharing
The cached roads data is written to a BigQuery table that has been created within a Google-owned project and shared with you using an Analytics Hub listing. See Subscribe to listings for details on how to subscribe and access BigQuery table using the Analytics Hub listing.
You can use the selected-route-id to retrieve the input geometry later on, or
can identify or filter the output route records stored in the Big Query table.
This lets you conduct rich traffic data analytics on selected routes.
If you opt for near real-time traffic updates, the system will relay the traffic
data for each designated selected_route through a dedicated Cloud Pub/Sub
topic. See
Subscribe
to a topic for a quick overview on how to subscribe and consume messages
from Cloud PubSub topic.
Subsequently, you can correlate the real-time Pub/Sub data with the historical
roads data residing within BigQuery tables, utilizing the selected-route-id as
the primary reference. This lets you understand the changing traffic patterns
and detect developing traffic congestion in near real time.
How to use the Roads Selection API
| 1 | Get set up | Start with Set up your Google Cloud project and complete the setup instructions that follow. |
| 2 | Create a selected route | Create a sample route for which you would like to receive periodic traffic data. See a sample request for creating a selected route.. |
| 3 | Subscribe to Analytics Hub Listing | Open the Analytics Hub Data Exchange link (shared after successful onboarding). Open the listing Historical Roads Data. Click Subscribe to open the Create linked dataset dialog. Follow the steps to create linked dataset with your chosen name under your project. See required IAM roles in your project for this step. |
| 4 | Check Selected Route Status | Check route status through Get method or query the route_status table in your linked BigQuery dataset. |
| 5 | Check that the roads data is available | Verify if the data has been populated in your linked BigQuery dataset. The table: historical_travel_time includes historical travel time and geometry for your selected routes. Data should be available within an hour after routes are validated. |
| 6 | Validate the output route | Visualize the output route and validate if the geometry accurately represents the route you're interested in |
| 7 | Analyze the traffic data | You can use this data to analyze and understand trends in the traffic for a given route across multiple days. |
| 8 | Subscribe to near real time traffic updates | To get real time traffic data, subscribe to the Cloud PubSub topic publishing updates for your selected routes. Verify you're receiving traffic updates through the cloud PubSub topic projects/maps-platform-roads-management/topics/rmi-trafficinformation-your_project_id. See retrieve data from a pull based subscription for details on how to retrieve messages published to a cloud PubSub topic using a pull based subscription.
|