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 defina o SelectedRoute recurso. 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 create endpoint.

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"

Em caso de êxito, a API retorna o SelectedRoute recurso. A resposta inclui o selectedRouteId no campo name. Você pode usar esse selectedRouteId para recuperar ou excluir o recurso SelectedRoute.

O exemplo de código a seguir mostra a estrutura de uma resposta de create endpoint bem-sucedida.

{
  "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 batchCreate endpoint. Esse endpoint permite definir até 1.000 rotas em uma chamada.

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

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 requests matriz. 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 batchCreate endpoint:

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"

Em caso de êxito, a API retorna uma resposta que contém uma matriz dos SelectedRoute recursos criados.

O exemplo de código a seguir mostra a estrutura de uma batchCreate resposta de endpoint:

{
  "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 uma rota com pontos de referência 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 ponto de referência definido por sua latitude e longitude. Uma rota pode ter até 25 pontos de referência.

O exemplo de código a seguir mostra como criar um SelectedRoute com pontos de referência 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 Dados do Gerenciamento de Estradas, o SelectedRoute objeto 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 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 próximas diretrizes ao definir o routeAttributes campo:

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

Em seguida, você pode usar esses routeAttributes personalizados nos Dados do Gerenciamento de Estradas das seguintes maneiras:

  • Filtrar notificações do Pub/Sub:é possível definir filtros nas 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, você pode 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"