Calcular rotas

A ferramenta compute_routes retorna um trajeto entre uma origem e um destino para um determinado meio de transporte. A resposta inclui a distância e a duração do trajeto. Por padrão, as rotas são calculadas sem trânsito em tempo real. O Pro adiciona rotas que consideram o trânsito em tempo real e rotas com mais paradas intermediárias.

Nesta página, descrevemos as opções de solicitação, incluindo as opções Pro, o que a resposta contém e como as solicitações são faturadas. Para ver o esquema completo da ferramenta, consulte a referência de compute_routes.

Opções de solicitação

Opção Descrição
origin, destination Obrigatório. Cada um é um waypoint: um address (um endereço legível por humanos ou um Plus Code), um place_id ou um lat_lng. É possível misturar formatos, por exemplo, um endereço para a origem e um ID de lugar para o destino.
travel_mode O meio de transporte: DRIVE (padrão), WALK, BICYCLE ou TRANSIT. As rotas de WALK estão na versão Beta e, às vezes, podem não ter calçadas ou caminhos claros para pedestres. Esse aviso precisa ser mostrado ao usuário em todos os trajetos a pé exibidos no seu app.
routing_preference Como os dados de trânsito são usados para calcular o trajeto: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (padrão) ou ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, que é uma opção Pro. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL não é compatível com WALK ou BICYCLE. Consulte Rotas com informações de trânsito.
intermediate_waypoints Paradas ordenadas entre a origem e o destino. O trajeto passa por eles na ordem indicada. Uma solicitação pode incluir até 10 waypoints intermediários ou de 11 a 25 como uma opção Pro. Uma solicitação com mais de 25 retorna um erro INVALID_ARGUMENT. As rotas de transporte público não aceitam waypoints intermediários.
departure_time ou arrival_time Quando sair da origem ou chegar ao destino, como um carimbo de data/hora RFC 3339. Defina no máximo um. O padrão é a partida no horário atual. Para TRANSIT, o horário pode ser de até 7 dias no passado ou 100 dias no futuro. Para outros meios de transporte, o horário não pode ser no passado e pode ser de até 365 dias no futuro.
compute_alternative_routes Quando true, a resposta inclui rotas alternativas além da recomendada, quando disponíveis. O padrão é false.
include_polyline Quando true, cada trajeto na resposta inclui encodedPolyline. O valor padrão é false.
location_bias Uma latitude e longitude que influenciam como os waypoints de texto são resolvidos, por exemplo, para eliminar a ambiguidade de um endereço.

Opções Pro

Duas opções selecionam a SKU Pro. Uma solicitação que usa um ou ambos é faturada com a SKU Pro:

Opção Pro Quando usar
routing_preference teve o endereço definido como ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL O usuário pergunta sobre o trânsito, congestionamento ou um tempo de viagem que considera o trânsito atual. Consulte Rotas com informações de trânsito.
11 a 25 intermediate_waypoints O trajeto precisa de mais de 10 paradas entre a origem e o destino.

Todas as outras opções são faturadas com a SKU Essentials, incluindo o modo de viagem, o tempo, as rotas alternativas, as polilinhas e a polarização de local.

Rotas com base no trânsito

Por padrão, as rotas são calculadas sem condições de trânsito em tempo real (ROUTING_PREFERENCE_TRAFFIC_UNAWARE). Essa configuração tem a menor latência. É adequado para solicitações em que o trânsito não importa ou não se aplica, como rotas de caminhada ou planejamento aproximado.

Defina routing_preference como ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL para calcular o trajeto e a duração dele com as condições de trânsito atuais, quando os dados de trânsito estiverem disponíveis. Use-a quando o usuário perguntar quanto tempo leva um trajeto de carro agora. Para rotas de TRANSIT, essa configuração usa dados de transporte público em tempo real, como atrasos e cancelamentos, quando disponíveis. Ele não é compatível com rotas WALK ou BICYCLE. Essas solicitações retornam um erro INVALID_ARGUMENT. Essa é uma opção Pro, então a solicitação é faturada com a SKU Pro. A opção também adiciona latência.

Durante a GA restrita, se o projeto não estiver na lista de permissões do Pro, essa opção será tratada como ROUTING_PREFERENCE_TRAFFIC_UNAWARE. Para mais detalhes, consulte Opções do Pro durante a GA restrita.

Exemplo

A solicitação a seguir pede um trajeto de carro com reconhecimento de trânsito, uma parada intermediária e uma polilinha codificada. A cobrança é feita com base na SKU do Pro:

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Resposta

A resposta contém routes[], ordenados do mais para o menos recomendado. Apenas um trajeto é retornado, a menos que compute_alternative_routes seja true. Cada rota inclui:

  • distanceMeters: a distância do trajeto, em metros.
  • duration: o tempo necessário para percorrer o trajeto. Com ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, a duração considera as condições de trânsito.
  • encodedPolyline: o caminho do trajeto como uma polilinha codificada, quando include_polyline é true. Você pode usá-la para desenhar o trajeto em um mapa com outras APIs da Plataforma Google Maps.
  • attribution: a atribuição que você precisa mostrar com o trajeto. Consulte os requisitos de atribuição.

Opções do Pro durante a GA restrita

Durante a GA restrita, as opções Pro estão disponíveis apenas para projetos na lista de permissões Pro. Se o projeto ainda não estiver na lista de permissões:

  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL é tratado como ROUTING_PREFERENCE_TRAFFIC_UNAWARE, e a solicitação é faturada de acordo com a SKU do Essentials.
  • Uma solicitação com mais de 10 waypoints intermediários retorna um erro INVALID_ARGUMENT ("At most 10 intermediate waypoints are supported.").

Para solicitar acesso, consulte Opções Pro durante a GA restrita.

Faturamento e cotas

Cada solicitação compute_routes é um evento faturável:

Solicitar rotas alternativas, uma polilinha, um horário de partida ou chegada ou um modo de viagem diferente não altera a SKU.

A cota de compute_routes é de 300 consultas por minuto, por projeto, compartilhada por ambas as SKUs. Para preços, consulte a tabela de preços principal e a tabela de preços da Índia.

Limites

  • Uma solicitação pode incluir no máximo 25 waypoints intermediários. De 11 a 25 é uma opção Pro. Uma solicitação com mais retorna um erro INVALID_ARGUMENT.
  • As rotas de transporte público não aceitam waypoints intermediários. Uma solicitação de transporte público com waypoints intermediários retorna um erro INVALID_ARGUMENT.
  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL não é compatível com rotas a pé ou trajetos para bicicleta.
  • Para rotas de transporte público, os horários de partida e chegada podem ser de até 7 dias no passado ou 100 dias no futuro. Para outros meios de transporte, elas não podem estar no passado e podem ser de até 365 dias no futuro.
  • As coordenadas do waypoint precisam estar dentro de limites geográficos válidos (latitude de -90 a 90, longitude de -180 a 180).
  • A ferramenta não retorna etapas de navegação guiada, trechos ou detalhes da linha de transporte público.