Criar rotas selecionadas

Nesta página, descrevemos como criar rotas e adicionar atributos personalizados usando a API Roads Selection nas seções a seguir:

Criar uma rota

Para criar uma rota, envie uma solicitação POST para o endpoint create.

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

O corpo da solicitação precisa ser um objeto JSON que define o recurso SelectedRoute. Esse objeto especifica as seguintes informações:

  • Um objeto dynamicRoute com as seguintes informações:
  • Um selectedRouteId exclusivo. Esse valor precisa ter entre 4 e 63 caracteres e usar apenas caracteres alfanuméricos. Se você não fornecer um ID, o sistema vai gerar um ID exclusivo para a rota selecionada.

O exemplo de código a seguir mostra a estrutura de uma solicitação POST para o endpoint 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"

Se a solicitação for bem-sucedida, a API vai retornar o recurso SelectedRoute. A resposta inclui o selectedRouteId no campo name. Use este selectedRouteId para recuperar ou excluir o recurso SelectedRoute.

A amostra de código a seguir mostra a estrutura de uma resposta bem-sucedida do endpoint 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"
}

Criar rotas em lote

Para criar várias rotas em uma única solicitação, use o endpoint batchCreate. Com esse endpoint, é possível definir até 1.000 rotas em uma chamada.

Envie uma solicitação POST para o endpoint batchCreate:

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

O URL usa a sintaxe de transcodificação gRPC.

O corpo da solicitação precisa ser um objeto JSON que contenha uma matriz requests. Cada objeto nessa matriz é um CreateSelectedRouteRequest que define um recurso SelectedRoute individual.

O exemplo de código a seguir mostra a estrutura de uma solicitação POST para o endpoint 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"

Se for bem-sucedida, a API vai retornar uma resposta que contém uma matriz dos recursos SelectedRoute criados.

O exemplo de código a seguir mostra a estrutura de uma resposta do endpoint 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"
    }
  ]
}

Criar um trajeto com pontos de referência intermediários

Para criar um trajeto que passe por pontos específicos entre a origem e o destino, inclua uma matriz intermediates no objeto dynamicRoute no corpo da solicitação. Cada elemento na matriz intermediates é um waypoint definido por latitude e longitude. Um trajeto pode ter até 25 waypoints.

O exemplo de código a seguir mostra como criar um SelectedRoute com pontos de parada intermediários:

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"

Usar atributos de rota personalizados

Para melhorar o gerenciamento de rotas e a análise de dados nos insights do Gerenciamento de estradas, o objeto SelectedRoute inclui um campo route_attributes.

Use o campo routeAttributes para definir suas próprias propriedades personalizadas para rotas individuais, em que cada atributo é um par de chave-valor. É possível fornecer até 10 pares de chave-valor personalizados por rota.

Esses atributos são úteis para identificar rotas específicas ou agrupar rotas com base em critérios relevantes para suas necessidades.

Confira alguns exemplos de atributos de rota que você pode usar:

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

Siga as diretrizes abaixo ao definir o campo routeAttributes:

  • As chaves não podem começar com o prefixo goog.
  • O comprimento de cada chave e valor não pode exceder 100 caracteres.

É possível usar esses routeAttributes personalizados nos Insights de gerenciamento de vias das seguintes maneiras:

  • Filtrar notificações do Pub/Sub:é possível definir filtros nas suas assinaturas do Pub/Sub para receber atualizações apenas de rotas que correspondem ou não a chaves de atributo específicas e aos valores correspondentes.
  • Refinar a análise do BigQuery:nas tabelas do BigQuery, é possível usar esses atributos para filtrar rotas específicas com base no valor de um atributo. Também é possível agrupar rotas por uma chave de atributo específica para uma análise de dados mais direcionada.

O exemplo de código a seguir mostra como criar um SelectedRoute com 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"