Como receber direções pela API Directions (legada)

Desenvolvedores do Espaço Econômico Europeu (EEE)

Este produto está no status legado. A partir de outubro de 2026, a API Directions (legada) não poderá mais ser ativada para novos projetos na nuvem do Google Cloud. Os projetos atuais continuam totalmente compatíveis. Para novos recursos e melhor desempenho, migre para a API Routes.

Para cálculos de rotas que respondem em tempo real à entrada do usuário (por exemplo, em um elemento da interface do usuário), use a API Directions (legada) ou, se estiver usando a API Maps JavaScript, use o serviço Directions. Para uso do lado do servidor, você pode usar os clientes Java, Python, Go e Node.js para serviços do Google Maps.

Com a API Directions (legada), você pode:

  • Pesquise rotas para vários meios de transporte, incluindo transporte público, carro, a pé ou bicicleta.
  • Retornar rotas em várias partes usando uma série de pontos de referência.
  • Especifique origens, destinos e waypoints como strings de texto (por exemplo, "Chicago, IL" ou "Darwin, NT, Australia"), como IDs de lugar ou como coordenadas de latitude/longitude.

A API retorna as rotas mais eficientes ao calcular as rotas. O tempo de viagem é o principal fator otimizado, mas a API também pode considerar outros fatores, como distância, quantidade de curvas e muitos outros, ao decidir qual trajeto é o mais eficiente.

Antes de começar

Antes de usar a API Directions (legada), você precisa de um projeto com uma conta de faturamento e a API Directions (legada) ativada. Para saber mais, consulte Configurar no console do Cloud.

Criar solicitações da API Directions (legada)

Uma solicitação da API Directions (legada) tem o seguinte formato:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

em que outputFormat pode ser um dos seguintes valores:

  • json (recomendado) indica a saída em JavaScript Object Notation (JSON)
  • xml indica a saída como XML.

Observação: os URLs precisam ser codificados corretamente para serem válidos e estão limitados a 16.384 caracteres em todos os serviços da Web. Considere esse limite ao criar seus URLs.

Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). Todos os caracteres reservados (por exemplo, o sinal de adição "+") precisam ser codificados em URL. Veja abaixo a lista de parâmetros e seus valores possíveis.

Parâmetros obrigatórios

  • destino

    O ID de lugar, o endereço ou o valor textual de latitude/longitude para o qual você quer calcular as rotas. As opções para o parâmetro de destino são as mesmas do parâmetro de origem.

  • origem

    O ID de lugar, endereço ou valor textual de latitude/longitude de onde você quer calcular as rotas.

    • Os IDs de lugar precisam ter o prefixo place_id:. É possível recuperar IDs de lugar das APIs Geocoding e Places (incluindo o Place Autocomplete). Para um exemplo que usa IDs de lugar do Place Autocomplete, consulte Place Autocomplete e Directions. Para mais informações sobre IDs de lugar, consulte a visão geral de IDs de lugar. 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • Se você transmitir um endereço, o serviço de rotas vai geocodificar a string e convertê-la em uma coordenada de latitude/longitude para calcular as rotas. Essa coordenada pode ser diferente da retornada pela API Geocoding, por exemplo, a entrada de um edifício em vez do centro dele. 

      origin=24+Sussex+Drive+Ottawa+ON

      É preferível usar IDs de lugar em vez de endereços ou coordenadas de latitude/longitude. O uso de coordenadas sempre vai resultar no ajuste do ponto à via mais próxima dessas coordenadas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma via que leve ao destino de forma rápida ou segura.

    • Se você transmitir coordenadas, o ponto será ajustado à via mais próxima. É preferível transmitir um ID de lugar. Se você transmitir coordenadas, verifique se não há espaço entre os valores de latitude e longitude. 

      origin=41.43206,-81.38992

    • Os Plus Codes precisam ser formatados como um código global ou composto. Formate os Plus Codes conforme mostrado aqui (os sinais de adição têm escape de URL para %2B e os espaços, para %20).

      • O código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9 é 849VCWC8%2BR9).
      • O código composto é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9 Mountain View, CA, EUA é CWC8%2BR9%20Mountain%20View%20CA%20USA).
    Observação: para maior eficiência e precisão, use IDs de lugar sempre que possível. Esses IDs são explicitamente exclusivos, como um par de valores de latitude/longitude, e oferecem benefícios de geocodificação para rotas, como pontos de acesso e variáveis de trânsito. Ao contrário de um endereço, os IDs não exigem que o serviço realize uma pesquisa ou uma solicitação intermediária de Place Details. Portanto, o desempenho é melhor.

Parâmetros opcionais

  • alternativas

    Se definido como true, especifica que o serviço Directions pode fornecer mais de uma opção de trajeto na resposta. Fornecer opções de trajeto pode aumentar o tempo de resposta do servidor. Disponível apenas para solicitações sem waypoints intermediários. Para mais informações, consulte o guia sobre waypoints.

  • arrival_time

    Especifica o horário de chegada preferencial para rotas de transporte público, em segundos desde a meia-noite de 1º de janeiro de 1970 UTC. É possível especificar departure_time ou arrival_time, mas não ambos. arrival_time precisa ser especificado como um número inteiro.

  • evitar

    Indica que as rotas calculadas precisam evitar os recursos indicados. Esse parâmetro oferece suporte para os seguintes argumentos:

    • tolls indica que o trajeto calculado deve evitar vias/pontes com pedágio.
    • highways indica que o trajeto calculado deve evitar rodovias.
    • ferries indica que o trajeto calculado deve evitar balsas.
    • indoor indica que o trajeto calculado deve evitar etapas internas para rotas de transporte público e a pé.

    É possível solicitar um trajeto que evite qualquer combinação de pedágios, rodovias e balsas transmitindo várias restrições ao parâmetro avoid. Exemplo: 

    avoid=tolls|highways|ferries.

  • departure_time

    Especifica o horário de partida preferencial. É possível especificar o horário como um número inteiro em segundos desde a meia-noite de 1º de janeiro de 1970 UTC. Se um departure_time posterior a 9999-12-31T23:59:59.999999999Z for especificado, a API vai reverter o departure_time para 9999-12-31T23:59:59.999999999Z. Como alternativa, é possível especificar um valor de now, que define o horário de partida como o horário atual (correto para o segundo mais próximo). A hora de saída pode ser especificada em dois casos:

    • Para solicitações em que o meio de transporte é o transporte público: é possível especificar departure_time ou arrival_time. Se nenhum horário for especificado, o departure_time será definido como o horário atual (ou seja, o horário de partida será o horário atual).
    • Para solicitações em que o meio de transporte é de carro: é possível especificar o departure_time para receber um trajeto e uma duração de viagem (campo de resposta: duration_in_traffic) que consideram as condições de trânsito. O departure_time precisa ser definido como o horário atual ou no futuro. Seu valor não pode estar no passado.
    Observação: as opções de trajeto e duração se baseiam na rede viária e nas condições médias de trânsito (independente da hora) quando o horário de partida não é especificado. Os resultados das solicitações variam em função de mudanças na rede viária, atualizações nas condições de trânsito e da natureza distribuída do serviço. Eles também variam entre trajetos quase equivalentes a qualquer momento ou frequência.
    Observação: as solicitações da matriz de distância que especificam departure_time quando mode=driving são limitadas a no máximo 100 elementos por solicitação. O número de origens multiplicado pelo número de destinos define o número de elementos.

  • language

    O idioma em que os resultados serão retornados. Isso se aplica apenas aos endereços geocodificados em start_address e end_address, ao texto localizado nos campos distance e duration (em trechos e etapas) e à descrição de manobras em html_instructions, mas não aos nomes e endereços em html_instructions, que são formatados no idioma e na escrita locais.

    • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
    • Se language não for fornecido, a API vai tentar usar o idioma preferencial, conforme especificado no cabeçalho Accept-Language.
    • A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores locais. Para isso, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, que é escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
    • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.

  • modo

    Para o cálculo de distâncias e rotas, você pode especificar o meio de transporte a ser usado. Por padrão, o modo driving é usado. Por padrão, as rotas são calculadas como rotas de driving . Os seguintes meios de transporte são aceitos:

    • driving (padrão) indica rotas de carro ou distância padrão usando a rede viária.
    • walking solicita rotas a pé ou distância por faixas de pedestre e calçadas (quando disponível).
    • bicycling solicita rotas de bicicleta ou distância usando ciclovias e ruas preferenciais (quando disponível).
    • transit solicita rotas ou distância usando trajetos de transporte público (quando disponível). Se você definir o modo como transporte público, poderá especificar um departure_time ou um arrival_time. Se nenhum horário for especificado, o departure_time será definido como o horário atual (ou seja, o horário de partida será o horário atual). Também é possível incluir um transit_mode e/ou um transit_routing_preference. As viagens de transporte público ficam disponíveis por até 7 dias no passado ou até 100 dias no futuro, sujeitas à disponibilidade de informações de transporte público fornecidas pelos provedores de dados. Os horários de transporte público mudam com frequência, as viagens disponíveis podem mudar ao longo do tempo e não há garantia de resultados consistentes para previsões com muita antecedência.
    Observação: às vezes, as rotas a pé e de bicicleta não incluem caminhos claros para pedestres ou ciclistas. Portanto, elas vão retornar avisos no resultado, que você precisa mostrar ao usuário.

  • região

    O código da região, especificado como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").

  • traffic_model

    Especifica as premissas que serão usadas no cálculo do tempo no trânsito. Essa configuração afeta o valor retornado no campo duration_in_traffic na resposta, que contém o tempo previsto no trânsito com base nas médias históricas. O parâmetro traffic_model só pode ser especificado para rotas de carro em que a solicitação inclui um departure_time. Os valores disponíveis para esse parâmetro são:

    • best_guess (padrão) indica que o valor retornado de duration_in_traffic deve ser a melhor estimativa do tempo de viagem, considerando as informações de condições de trânsito históricas e em tempo real. Quanto mais próximo de agora for o departure_time, mais importante será o trânsito em tempo real.
    • pessimistic indica que o valor retornado de duration_in_traffic deve ser maior que o tempo de viagem na maioria dos dias, embora ele possa ser maior em alguns dias em que as condições de trânsito são particularmente ruins.
    • optimistic indica que o valor retornado de duration_in_traffic deve ser menor que o tempo de viagem na maioria dos dias, embora ele possa ser menor em alguns dias em que as condições de trânsito são particularmente boas.

    O valor padrão de best_guess vai fornecer as previsões mais úteis para a grande maioria dos casos de uso. É possível que a previsão de tempo de viagem de best_guess seja menor que optimistic ou maior que pessimistic, devido à forma como o modelo preditivo de best_guess integra informações de trânsito em tempo real.

  • transit_mode

    Especifica um ou mais meios de transporte preferenciais. Esse parâmetro só pode ser especificado para rotas de transporte público. O parâmetro é compatível com os seguintes argumentos:

    • bus indica preferência ao deslocamento por ônibus no trajeto calculado.
    • subway indica preferência ao deslocamento por metrô no trajeto calculado.
    • train indica preferência ao deslocamento por trem no trajeto calculado.
    • tram indica preferência ao deslocamento por bonde e veículo leve sobre trilhos (VLT) no trajeto calculado.
    • rail indica preferência ao deslocamento por trem, bonde, veículo leve sobre trilhos (VLT) e metrô no trajeto calculado. É equivalente a transit_mode=train|tram|subway.

  • transit_routing_preference

    Especifica as preferências para rotas de transporte público. Com esse parâmetro, é possível direcionar as opções retornadas em vez de aceitar o melhor trajeto padrão escolhido pela API. Esse parâmetro só pode ser especificado para rotas de transporte público. O parâmetro oferece suporte para os seguintes argumentos:

    • less_walking indica preferência por pouca caminhada no trajeto calculado.
    • fewer_transfers indica preferência por um número limitado de baldeações no trajeto calculado.

  • unidades

    Especifica o sistema de unidades a ser usado ao exibir os resultados.

    Os resultados de rotas contêm texto nos campos de distância que podem ser mostrados ao usuário para indicar a distância de uma determinada "etapa" do trajeto. Por padrão, esse texto usa o sistema de unidades do país ou da região de origem.

    Por exemplo, um trajeto de "Chicago, IL" para "Toronto, ONT" mostra resultados em milhas, enquanto o trajeto inverso mostra resultados em quilômetros. É possível substituir esse sistema de medidas configurando outro sistema explicitamente no parâmetro de unidades da solicitação, transmitindo um dos seguintes valores:

    • metric especifica o uso do sistema métrico. As distâncias textuais são retornadas em quilômetros e metros.
    • imperial especifica o uso do sistema imperial (inglês). Distâncias textuais são retornadas em milhas e pés.
    Observação: essa configuração do sistema de medidas afeta apenas o texto mostrado nos campos de distância. Os campos de distância também contêm valores que são sempre expressos em metros.

  • waypoints

    Cuidado: as solicitações que usam mais de 10 waypoints (entre 11 e 25) ou a otimização de waypoints têm uma taxa mais alta. Saiba mais sobre o faturamento dos produtos da Plataforma Google Maps.

    Especifica uma matriz de locais intermediários para incluir ao longo do trajeto entre os pontos de origem e destino como locais de passagem ou parada. Os waypoints mudam um trajeto desviando-o por localizações específicas. A API aceita waypoints para os seguintes meios de transporte: carro, a pé e bicicleta, mas não transporte público. Você pode fornecer um ou mais locais separados pelo caractere de barra vertical (| ou %7C), na forma de um ID de lugar, um endereço ou coordenadas de latitude/longitude. Por padrão, o serviço Directions calcula um trajeto usando os waypoints na ordem em que são fornecidos. A precedência para analisar o valor do waypoint é o ID de lugar, as coordenadas de latitude/longitude e o endereço.

    • Se você transmitir um ID de lugar, ele precisará ter o prefixo place_id:. É possível recuperar IDs de lugar das APIs Geocoding e Places (incluindo o Place Autocomplete). Para um exemplo que usa IDs de lugar do Place Autocomplete, consulte Place Autocomplete e Directions. Para mais informações sobre IDs de lugar, consulte a visão geral de IDs de lugar.
      Para maior eficiência e precisão, use IDs de lugar sempre que possível. Esses IDs são explicitamente exclusivos, como um par de valores de latitude/longitude, e oferecem benefícios de geocodificação para rotas, como pontos de acesso e variáveis de trânsito. Ao contrário de um endereço, os IDs não exigem que o serviço realize uma pesquisa ou uma solicitação intermediária de Place Details. Portanto, o desempenho é melhor.
    • Se você transmitir coordenadas de latitude/longitude, os valores vão diretamente para o servidor de front-end para calcular as rotas sem geocodificação. Os pontos são ajustados às vias e podem não fornecer a precisão que seu app precisa. Use coordenadas quando tiver certeza de que os valores realmente especificam os pontos que seu app precisa para definir rotas, sem considerar possíveis pontos de acesso ou outros detalhes de geocodificação. Verifique se uma vírgula (%2C), e não um espaço (%20), separa os valores de latitude e longitude.
    • Se você transmitir um endereço, o serviço de rotas vai geocodificar a string e convertê-la em coordenadas de latitude/longitude para calcular as rotas. Se o valor do endereço for ambíguo, ele poderá evocar uma pesquisa para eliminar a ambiguidade de endereços semelhantes. Por exemplo, "Rua 1" pode ser um valor completo ou parcial para "Rua 1 NE" ou "Rua 1 SE". Esse resultado pode ser diferente do retornado pela API Geocoding. Para evitar possíveis interpretações incorretas, use IDs de lugar.
    • Como alternativa, você pode fornecer um conjunto codificado de pontos usando o algoritmo de polilinha codificada. Um conjunto codificado é útil para um grande número de waypoints, porque o URL é significativamente mais curto. Todos os serviços da Web têm um limite de URL de 16.384 caracteres.
      • As polilinhas codificadas precisam ter o prefixo enc: e ser seguidas por dois-pontos (:). Por exemplo: waypoints=enc:gfo}EtohhU:.
      • Também é possível incluir várias polilinhas codificadas, separadas pelo caractere de barra vertical (|). Por exemplo, waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:.
    Influenciar rotas com pontos de parada e passagem

    Para cada ponto de passagem na solicitação, a resposta de rotas adiciona uma entrada à matriz legs para fornecer os detalhes das paradas nesse trecho do trajeto.

    Se você quiser influenciar o trajeto usando waypoints sem adicionar uma parada, adicione o prefixo via: ao waypoint. Os waypoints com o prefixo via: não adicionam uma entrada à matriz legs, mas direcionam o trajeto pelo waypoint.

    O URL a seguir modifica a solicitação anterior para que o trajeto seja roteado por Lexington sem paradas: 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

    O prefixo via: é mais eficaz ao criar rotas em resposta ao usuário arrastando os waypoints no mapa. Isso permite que o usuário veja como será o trajeto final em tempo real e ajuda a garantir que os waypoints sejam colocados em locais acessíveis à API Directions.

    Atenção: usar o prefixo via: para evitar paradas resulta em rotas que são rígidas na interpretação do waypoint. Essa interpretação poderá resultar em desvios graves no trajeto ou ZERO_RESULTS no código de status da resposta, se a API Directions não conseguir criar rotas usando esse ponto.
    Otimizar seus pontos de referência

    Por padrão, o serviço Directions calcula um trajeto pelos waypoints fornecidos, na ordem em que são apresentados. Como opção, você pode passar optimize:true como o primeiro argumento no parâmetro de waypoints para permitir que o serviço Directions otimize o trajeto fornecido reorganizando os waypoints em uma ordem mais eficaz. Essa otimização é um aplicativo do problema do vendedor de viagens. O tempo de viagem é o principal fator a ser otimizado, mas demais fatores, como distância, quantidade de curvas e outros, podem ser considerados para determinar a rota mais eficaz. Todos os waypoints precisam ser paradas para que o serviço Directions otimize o trajeto.

    Se você instruir o serviço Directions a otimizar a ordem dos seus waypoints, a ordem será retornada no campo waypoint_order dentro do objeto de rotas. O campo waypoint_order retorna valores baseados em zero.

    O exemplo a seguir calcula uma viagem de carro de Adelaide, no sul da Austrália, até cada uma das principais regiões vinícolas do sul da Austrália usando a otimização de rotas. 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

    A inspeção do trajeto calculado vai indicar que o cálculo usa waypoints na seguinte ordem: 

    "waypoint_order": [ 3, 2, 0, 1 ]
    Cuidado: as solicitações que usam a otimização de waypoints têm uma taxa mais alta. Saiba mais sobre o faturamento dos produtos da Plataforma Google Maps.

A seguir

Exemplos de rotas

Respostas do Directions