Criar rotas selecionadas

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

Criar uma rota

Para criar uma rota, envie uma solicitação POST ao 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 de 4 a 63 caracteres, e os caracteres válidos são a-z, A-Z, 0-9, - ou _. Se um ID não for fornecido, o sistema vai gerar um ID exclusivo para a rota selecionada.

Criar uma rota fixa (padrão)

Por padrão, os trajetos são criados como fixos e permanecem consistentes com a geometria de trajeto estático (exportada para a tabela do BigQuery routes_status) calculada no momento da criação sem trânsito em tempo real. Isso garante o monitoramento consistente dos dados de tráfego sem que ele seja afetado por mudanças nas condições de trânsito.

Defina o campo booleano dynamicRouting no corpo da solicitação para especificar se a rota é fixa (false, o padrão) ou dinâmica (true).

O exemplo de código a seguir mostra a estrutura de uma solicitação POST para create uma rota fixa.

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"

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

O exemplo 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",
  "dynamicRouting": false
}

Criar uma rota dinâmica

Também é possível criar uma rota dinâmica definindo o campo dynamicRouting como true. A geometria do trajeto pode mudar devido às condições de trânsito, porque a plataforma de rotas do Google sempre encontra o melhor trajeto.

O exemplo de código a seguir mostra a estrutura de uma solicitação POST para create uma rota dinâmica:

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"

O exemplo 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",
  "dynamicRouting": true
}

Criar uma rota com waypoints 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. Uma rota pode ter até 25 waypoints.

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

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"

Usar atributos de rota personalizados

Para melhorar o gerenciamento de rotas e a análise de dados no Dados do Gerenciamento de Estradas, o objeto SelectedRoute inclui um campo routeAttributes.

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é 25 pares de chave-valor personalizados por rota.

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

Veja 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 tamanho de cada chave e de cada valor não pode exceder 100 caracteres.

Em seguida, use esses routeAttributes personalizados nos Dados do Gerenciamento de Estradas 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 correspondam ou não a chaves de atributos 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 próximo exemplo de código mostra como criar um SelectedRoute com routeAttributes personalizados.

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"

Criar rotas em lote

Para criar várias rotas em uma única solicitação, use o endpoint batchCreate. Esse endpoint permite 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": [
        {
          "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"

Se a solicitação for bem-sucedida, a API vai retornar uma resposta com uma matriz dos recursos SelectedRoute que foram 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",
      "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
    }
  ]
}