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 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 entre 4 e 63 caracteres e usar apenas caracteres alfanuméricos. Se você não fornecer um ID, o sistema vai gerar um 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 '
    {
      "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 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.

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

Criar uma rota com waypoints intermediários

Para criar uma rota 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 '
    {
      "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 nos Dados do Gerenciamento de Estradas, o objeto SelectedRoute inclui um campo routeAttributes.

Use o campo routeAttributes para definir 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.

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.

Depois, 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 correspondem ou não a chaves de atributos específicos e seus 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. Você também pode agrupar rotas por uma chave de atributo específica para uma análise de dados mais segmentada.

O exemplo de código a seguir 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. Com esse endpoint, é possível definir até mil rotas em uma única 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 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"
    }
  ]
}