Crea rutas seleccionadas

En esta página, se describe cómo crear rutas y agregar atributos personalizados con la API de Roads Selection en las siguientes secciones:

Crear una ruta

Para crear una ruta, envía una solicitud POST al extremo create.

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

El cuerpo de la solicitud debe ser un objeto JSON que defina el recurso SelectedRoute. Este objeto especifica la siguiente información:

  • Un objeto dynamicRoute con la siguiente información:
    • El origin de la ruta seleccionada.
    • El destination de la ruta seleccionada.
    • Cualquier intermediates, también conocido como punto de referencia, de la ruta.
  • Un selectedRouteId único. Este valor debe tener entre 4 y 63 caracteres, y solo debe usar caracteres alfanuméricos. Si no proporcionas un ID, el sistema generará uno único para la ruta seleccionada.

En el siguiente ejemplo de código, se muestra la estructura de una solicitud POST al extremo create.

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"

Si la operación se realiza correctamente, la API devuelve el recurso SelectedRoute. La respuesta incluye el selectedRouteId en el campo name. Puedes usar este selectedRouteId para recuperar o borrar el recurso SelectedRoute.

En el siguiente ejemplo de código, se muestra la estructura de una respuesta correcta del extremo de create.

{
  "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"
}

Crea rutas por lotes

Para crear varias rutas en una sola solicitud, usa el extremo batchCreate. Este extremo te permite definir hasta 1,000 rutas en una sola llamada.

Envía una solicitud POST al extremo batchCreate:

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

La URL usa la sintaxis de la transcodificación de gRPC.

El cuerpo de la solicitud debe ser un objeto JSON que contenga un array de requests. Cada objeto dentro de este array es un CreateSelectedRouteRequest que define un recurso SelectedRoute individual.

En la siguiente muestra de código, se muestra la estructura de una solicitud de POST al extremo de batchCreate:

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"

Si la operación se realiza correctamente, la API devuelve una respuesta que contiene un array de los recursos SelectedRoute que se crearon.

En el siguiente ejemplo de código, se muestra la estructura de una respuesta del extremo batchCreate:

{
  "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"
    }
  ]
}

Crea una ruta con puntos de referencia intermedios

Para crear una ruta que pase por puntos específicos entre el origen y el destino, incluye un array intermediates dentro del objeto dynamicRoute en el cuerpo de la solicitud. Cada elemento del array intermediates es un punto de referencia definido por su latitude y longitude. Una ruta puede tener hasta 25 puntos de referencia.

En el siguiente ejemplo de código, se muestra cómo crear un objeto SelectedRoute con puntos de ruta intermedios:

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"

Utiliza atributos de ruta personalizados

Para mejorar la administración de rutas y el análisis de datos en Roads Management Insights, el objeto SelectedRoute incluye un campo route_attributes.

Usa el campo routeAttributes para definir tus propias propiedades personalizadas para rutas individuales, en las que cada atributo es un par clave-valor. Puedes proporcionar hasta 10 pares clave-valor personalizados por ruta.

Estos atributos son útiles para identificar rutas específicas o agruparlas según criterios relevantes para tus necesidades.

A continuación, se incluyen algunos ejemplos de atributos de ruta que podrías usar:

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

Sigue los siguientes lineamientos cuando definas el campo routeAttributes:

  • Las claves no deben comenzar con el prefijo goog.
  • La longitud de cada clave y cada valor no debe superar los 100 caracteres.

Luego, puedes usar estos routeAttributes personalizados en las estadísticas de administración de rutas de las siguientes maneras:

  • Filtra las notificaciones de Pub/Sub: Puedes establecer filtros en tus suscripciones a Pub/Sub para recibir actualizaciones solo de las rutas que coincidan o no con claves de atributos específicos y sus valores correspondientes.
  • Refina el análisis de BigQuery: En tus tablas de BigQuery, puedes usar estos atributos para filtrar rutas específicas según el valor de un atributo. También puedes agrupar las rutas por una clave de atributo específica para realizar un análisis de datos más segmentado.

En el siguiente ejemplo de código, se muestra cómo crear un SelectedRoute con routeAttributes personalizados.

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"