Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps Directions API

Para começar, orientaremos você pelo Google Developers Console para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps Directions API
  3. Criar chaves apropriadas
Continuar

Guia do desenvolvedor

A Google Maps Directions API é um serviço que calcula rotas entre locais usando uma solicitação HTTP.

Este serviço também está disponível como parte da Google Maps JavaScript API do lado do cliente ou para uso do lado do servidor com Java Client, Python Client, Go Client e Node.js Client for Google Maps Services. Observação: Os mesmos limites de uso diários se aplicam independentemente de como você usa o serviço. As solicitações por dia são calculadas como a soma das consultas do lado do cliente e do lado do servidor.

Este documento é destinado a desenvolvedores de sites e dispositivos móveis que desejam calcular dados de rotas em mapas fornecidos por uma das Google Maps APIs. Ele fornece uma introdução sobre como usar a API e materiais de referência sobre os parâmetros disponíveis.

Introdução

Este vídeo demonstra o uso da Google Maps Directions API para ajudar as pessoas a encontrar os melhores caminhos. O vídeo inclui conselhos sobre como usar proxies para o serviço web via seu servidor ao usar a API em um aplicativo móvel para proteger a chave da API.

Com a Directions API, você pode:

  • Procure rotas para diversos modos de transporte, incluindo transporte público, condução, caminhada ou bicicleta.
  • Retorna rotas em várias partes usando uma série de pontos de referência.
  • Especifique origens, destinos e pontos de referências como strings de texto (por exemplo: "Chicago, IL" ou "Darwin, NT, Austrália") ou como coordenadas de latitude/longitude ou IDs de local.

O cálculo de rotas é uma tarefa que demanda muito tempo e recursos. Sempre que possível, calcule endereços conhecidos antecipadamente (usando o serviço aqui descrito) e armazene os resultados em um cache temporário que tenha projetado.

Observação: Este serviço não é projetado para responder em tempo real à entrada do usuário. Para calcular rotas dinâmicas (por exemplo, em um elemento de interface do usuário, consulte a documentação do serviço de rotas da Google Maps JavaScript API.

Antes de começar a desenvolver com a Directions API, consulte os requisitos de autenticação (chave de API necessária) e os limites de uso da API.

Solicitações de rotas

Uma solicitação da Google Maps Directions API tem o seguinte formato:

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

onde outputFormat pode ser qualquer um dos seguintes valores:

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

Observação: URLs devem ser codificados corretamente para serem válidos e são limitados a 8192 caracteres para todos os serviços Web. Lembre-se deste limite ao construir seus URLs.

HTTPS ou HTTP

A segurança é importante e recomenda-se o uso de HTTPS sempre que possível, principalmente para aplicativos que incluam dados confidenciais de usuários nas solicitações, como a localização. O uso da criptografia HTTPS torna o aplicativo mais seguro e mais resistente a invasões ou adulterações.

Se não for possível usar HTTPS, para acessar a Google Maps Directions API por HTTP, use:

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

Parâmetros de solicitação

Alguns parâmetros são obrigatórios e outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). A lista de parâmetros e os possíveis valores estão enumerados abaixo.

Parâmetros obrigatórios

  • origin — o endereço, valor textual de latitude/longitude ou ID de local que deseja usar como ponto de partida para calcular rotas.
    • Se você passar um endereço, o serviço Directions gera o código geográfico da string e o converte em coordenadas de latitude/longitude para calcular rotas. Essas coordenadas podem ser diferentes das retornadas pela Google Maps Geocoding API, indicando, por exemplo, a entrada de um edifício em vez de seu centro.
      origin=24+Sussex+Drive+Ottawa+ON
    • Se você passar coordenadas, elas serão usadas no estado em que se encontram para calcular rotas. Não insira espaços entre os valores de latitude e longitude.
      origin=41.43206,-81.38992
    • IDs de local devem ser precedidos por place_id:. O ID de local só poderá ser especificado se a solicitação incluir uma chave de API ou um ID de cliente da Google Maps APIs Premium Plan. É possível recuperar IDs de local da Google Maps Geocoding API e da Google Places API (incluindo Place Autocomplete). Para obter um exemplo sobre como usar IDs de local da Place Autocomplete, consulte Place Autocomplete e rotas. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination — o endereço, valor textual de latitude/longitude ou ID de local que deseja usar como ponto de chegada para calcular rotas. As opções para o parâmetro destination são as mesmas do parâmetro origin, conforme descrito acima.
  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como obter uma chave.

    Observação: clientes Google Maps APIs Premium Plan podem usar uma chave de API ou um ID de cliente válido e uma assinatura digital nas solicitações do Directions. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Parâmetros opcionais

  • mode (o padrão é driving) — especifica o modo de transporte a ser usado ao calcular a rota. Valores válidos e outros detalhes sobre solicitações são especificados em Modos de transporte.
  • waypoints — especifica uma série de pontos de referência. Pontos de referência alteram uma rota desviando-a por locais específicos. Um ponto de referência é especificado como uma coordenada de latitude/longitude, uma polilinha codificada, um ID de local ou um endereço que será geocodificado. Polilinhas codificadas devem ser prefixadas com enc: seguido do sinal de dois pontos (:). IDs de local devem ser precedidos por place_id:. O ID de local só poderá ser especificado se a solicitação incluir uma chave de API ou um ID de cliente da Google Maps APIs Premium Plan. Pontos de referência são suportados apenas para rotas de bicicleta, trânsito ou caminhadas. Para obter mais informações sobre pontos de referência, consulte o guia para pontos de referência abaixo.
  • alternatives — se esse parâmetro é definido como true, ele especifica que o serviço da Directions API poderá fornecer mais de uma alternativa de rota em resposta. Observe que fornecer rotas alternativas pode aumentar o tempo de resposta do servidor.
  • avoid — indica que as rotas calculadas devem evitar os componentes indicados. Esse parâmetro oferece suporte para os seguintes argumentos:
    • tolls indica que a rota calculada deve evitar vias ou pontes com pedágio.
    • highways indica que a rota calculada deve evitar rodovias.
    • ferries indica que a rota calculada deve evitar balsas.
    • indoor indica que a rota calculada deve evitar etapas que passem por dentro de edifícios para rotas de caminhada e transporte público. Somente solicitações que incluam uma chave de API ou um ID de cliente da Google Maps APIs Premium Plan receberão esse tipo de etapa por padrão.
    Para saber mais, consulte a seção Restrições de rota abaixo.
  • language — o idioma no qual retornar os resultados.
    • Confira a lista de idiomas suportados. O Google atualiza os idiomas suportados com frequência, portanto, esta lista pode não estar completa.
    • Se language não for fornecido, a API tentará usar o idioma preferencial conforme especificado no cabeçalho Accept-Language ou o idioma nativo do domínio do qual a solicitação foi enviada.
    • A API faz o possível para fornecer um endereço residencial legível tanto para o usuário quanto para os locais. Para atingir este objetivo, ele retorna os endereços residenciais no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferencial. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, escolhido pelo primeiro componente.
    • Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
    • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe para retornar e na ordem em que é retornado. O codificador geográfico interpreta abreviações de formas variadas dependendo do idioma, como abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outros. Por exemplo, utca e tér são sinônimos para ruas em húngaro.
  • units — especifica o sistema de unidades a ser usado ao exibir os resultados. Valores válidos são especificados na seção Sistemas de unidade abaixo.
  • region — especifica o código de região como um valor de ccTLD ("domínio de nível superior") de dois caracteres. (Para saber mais, consulte a seção Direcionamento de região abaixo.)
  • arrival_time — especifica a hora desejada de chegada para solicitações de rota em segundos a partir da meia-noite (UTC) do dia 1º de janeiro de 1970. É possível especificar departure_time ou arrival_time, mas não ambos os parâmetros. Observe que arrival_time deve ser especificado como um número inteiro.
  • departure_time — especifica a hora de saída desejada. Essa hora pode ser especificada como um número inteiro em segundos a partir da meia-noite (UTC) do dia 1º de janeiro de 1970. Como alternativa, também é possível especificar um valor now, que define a hora de saída para o horário atual (correto até o segundo). A hora de saída pode ser especificada em dois casos:
    • Para solicitações cujo modo de transporte é transporte público: Você tem a opção de especificar um departure_time ou arrival_time. Se nenhum desses valores for especificado, o valor padrão de departure_time será "now" (ou seja, o horário de partida padrão é o atual).
    • Para solicitações cujo modo de transporte é condução: Você pode especificar o departure_time para receber uma rota e a duração do trajeto (campo de resposta: duration_in_traffic) que consideram as condições de trânsito. Essa opção é disponibilizada somente se a solicitação contém uma chave de API válida ou um ID de cliente da Google Maps APIs Premium Plan e uma assinatura válidos. O departure_time deve ser definido como o horário atual ou como um horário no futuro. Seu valor não deve estar no passado.
  • traffic_model (o padrão é best_guess) — especifica as suposições a serem usadas ao calcular o tempo no trânsito. Essa configuração afeta o valor retornado no campo duration_in_traffic da resposta, que contém a previsão de tempo baseada em médias históricas. O parâmetro traffic_model só pode ser especificado para rotas de condução cuja solicitação inclua um valor de departure_time, e somente se ela incluir uma chave de API ou um ID de cliente do Google Maps APIs Premium Plan. Os valores disponíveis para esse parâmetro são:
    • best_guess (padrão) indica que o valor duration_in_traffic retornado deve ser a melhor estimativa do tempo de percurso considerando o que se sabe sobre as condições históricas de trânsito e as informações em tempo real. As informações de trânsito em tempo real são mais importantes quando mais próximo do horário atual for o valor de departure_time.
    • pessimistic indica que o valor duration_in_traffic retornado deve ser maior do que o tempo de percurso real na maioria dos dias, mas dias ocasionais com condições de trânsito particularmente ruins podem exceder esse valor.
    • optimistic indica que o valor duration_in_traffic retornado deve ser menor do que o tempo de percurso real na maioria dos dias, mas dias ocasionais com condições de trânsito particularmente boas podem ser mais rápidos do que esse valor.
    O valor padrão de best_guess fornecerá as previsões mais úteis para a vasta maioria de casos de uso. A previsão do tempo de percurso de best_guess pode ser mais curto do que optimistic ou, como alternativa, mais longo que pessimistic devido à forma que o modelo de previsão best_guess integra informações de tráfego em tempo real.
  • transit_mode — especifica um ou mais modos de transporte preferenciais. Esse parâmetro só pode ser especificado para rotas de transporte público cuja solicitação incluir uma chave de API ou um ID de cliente do Google Maps APIs Premium Plan. O parâmetro oferece suporte para os seguintes argumentos:
    • bus indica que a rota calculada deve dar preferência ao transporte por ônibus.
    • subway indica que a rota calculada deve dar preferência ao transporte por metrô.
    • train indica que a rota calculada deve dar preferência ao transporte por trem.
    • tram indica que a rota calculada deve dar preferência ao transporte por bonde.
    • rail indica que a rota calculada deve dar preferência ao transporte por trem, bonde e metrô. Isso equivale a transit_mode=train|tram|subway.
  • transit_routing_preference — especifica preferências para rotas de transporte público. Com esse parâmetro, você pode polarizar as opções retornadas em vez de aceitar a melhor rota padrão escolhida pela API. Esse parâmetro só pode ser especificado para rotas de transporte público cuja solicitação incluir uma chave de API ou um ID de cliente do Google Maps APIs Premium Plan. O parâmetro oferece suporte para os seguintes argumentos:
    • less_walking indica que a rota calculada deve dar preferência a uma quantidade limitada de caminhada.
    • fewer_transfers indica que a rota calculada deve dar preferência a uma quantidade limitada de baldeações.

Exemplos de solicitações de rotas

A solicitação a seguir retorna uma rota de condução de Toronto, Ontário, para Montreal, Quebec.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

Ao alterar os parâmetros mode e avoid, a solicitação inicial pode ser modificada para retornar uma rota para uma jornada cênica de bicicleta que evite as principais rodovias.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

A solicitação a seguir procura rotas de transporte público de Brooklyn, Nova York para Queens, Nova York. A solicitação não especifica departure_time, portanto, é assumido o valor padrão, que é o horário atual.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

A solicitação a seguir inclui uma hora de partida específica.

Observação: neste exemplo, a hora de partida específica é 30 de julho de 2012 às 09:45. Para evitar erros, você deve alterar o parâmetro para um horário no futuro antes de enviar a solicitação.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

A solicitação a seguir retorna uma rota de condução de Glasgow, Reino Unido, para Perth, Reino Unido, usando IDs de local.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

Modos de transporte

Ao calcular rotas, você pode especificar o modo de transporte a ser usado com o parâmetro mode. Por padrão, as rotas são calculadas usando o modo driving. Os seguintes modos de transporte são permitidos:

  • driving (padrão) indica uma rota de condução padrão usando a rede de estradas.
  • walking solicita uma rota para caminhada por vias para pedestres e calçadas (quando disponíveis).
  • bicycling solicita uma rota para bicicleta por ciclovias e ruas preferencias (quando disponíveis).
  • transit solicita uma rota de transporte público (quando disponível). Se você definir o modo como transit, poderá especificar um valor de departure_time ou arrival_time. Se nenhum desses valores for especificado, o valor padrão de departure_time será “now” (ou seja, o horário de partida padrão é o atual). Há também a opção para incluir um transit_mode e/ou uma transit_routing_preference.

Observação: rotas para caminhada e bicicleta podem não incluir vias para pedestres ou ciclovias claras, portanto, essas rotas retornarão warnings no resultado, que devem ser exibidos ao usuário.

Pontos de referência

Ao calcular rotas usando a Google Maps Directions API, você também pode especificar pontos de referência para rotas de condução, caminhada e bicicleta. Os pontos de referência não estão disponíveis em rotas de transporte público. Pontos de referência permitem que você calcule rotas ao longo de locais adicionais, o que faz com que a rota retornada inclua paradas em cada ponto de referência fornecido.

Especifique os pontos de referência no parâmetro waypoints.

  • É possível fornecer um ou mais locais separados pelo caractere de barra reta (|), em forma de endereço, coordenadas de latitude/longitude ou ID de local:
    • Se você passar um endereço, o serviço Directions gerará o código geográfico da string e o converterá em coordenadas de latitude/longitude para calcular rotas. Essas coordenadas podem ser diferentes das retornadas pela Google Maps Geocoding API, indicando, por exemplo, a entrada de um edifício em vez de seu centro.
    • Se você passar coordenadas de latitude/longitude, elas serão usadas no estado em que se encontram para calcular rotas. Não insira espaços entre os valores de latitude e longitude.
    • Se você fornecer um ID de local, é preciso prefixá-lo com place_id:. Só é possível especificar um ID de local se a solicitação incluir uma chave de API ou um ID do cliente Google Maps APIs Premium Plan. É possível recuperar IDs de local da Google Maps Geocoding API e da Google Places API (incluindo Place Autocomplete). Para obter um exemplo sobre como usar IDs de local da Place Autocomplete, consulte Place Autocomplete e rotas. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local.
  • Como alternativa, é possível fornecer um conjunto codificado de coordenadas usando o Algoritmo de polilinha codificada. Isto é particularmente útil se você tem um grande número de pontos de referência, pois o URL é significativamente mais curto ao usar uma polilinha codificada.
    • Polilinhas codificadas devem ser prefixadas com enc: seguido do sinal de dois pontos (:). Por exemplo: waypoints=enc:gfo}EtohhU:
    • Também é possível incluir várias polilinhas codificadas, separadas pelo caractere de barra reta (|). Por exemplo: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

O URL a seguir inicia uma solicitação de rota entre Boston, MA e Concord, MA, com paradas em Charlestown e Lexington, nessa ordem:

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

Para cada ponto de referência da solicitação, a resposta da rota inclui uma entrada adicional na matriz legs para fornecer os detalhes correspondentes de cada trecho da jornada.

Se quiser influenciar a rota usando pontos de referência sem adicionar paradas, o ponto de referência deve ser precedido por via:. Pontos de referência precedidos por via: não adicionarão uma entrada na matriz legs, mas desviarão a rota pelo ponto de referência fornecido.

O URL a seguir modifica a solicitação anterior de forma que a jornada seja desviada por Lexington sem paradas:

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

O prefixo via: é mais eficiente ao criar rotas em resposta ao usuário arrastar pontos de referência pelo mapa. Isso permite que o usuário veja como será a rota final em tempo real e ajuda a garantir que os pontos de referência sejam posicionados em locais acessíveis para a Google Maps Directions API.

O URL a seguir solicita pontos de referência usando coordenadas de latitude/longitude:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Veja a mesma solicitação, usando uma polilinha codificada:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

Otimizar seus pontos de referência

Por padrão, o serviço Directions calcula uma rota pelos pontos de referência fornecidos, na ordem em que eles são apresentados. Também é possível passar optimize:true como primeiro argumento do parâmetro waypoints para permitir que o serviço da Directions API otimize a rota fornecida organizando os pontos de referência em uma ordem mais eficiente. (Essa otimização é uma aplicação do problema do caixeiro-viajante.) O tempo do percurso é o principal fator a ser otimizado, mas demais fatores, como distância, quantidade de curvas e outros, podem ser levados em consideração para se determinar a rota mais eficaz. Todos os pontos de referência devem ser paradas para que o serviço Directions otimize a rota.

Se você instruir o serviço da Directions API a otimizar a ordem dos pontos de referência, essa ordem será retornada no campo waypoint_order do objeto routes. O campo waypoint_order retorna valores com base zero.

O exemplo a seguir calcula uma rota de Adelaide, passando por cada uma das principais regiões vinícolas da Austrália Meridional usando a otimização de rota.

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&key=YOUR_API_KEY

Uma inspeção da rota calculada indicará que ela usa a seguinte ordem de pontos de referência:

"waypoint_order": [ 1, 0, 2, 3 ]

Restrições

As rotas podem ser calculadas aderindo a certas restrições. Restrições são indicadas pelo uso do parâmetro avoid e um argumento para esse parâmetro indicando a restrição a ser evitada. As seguintes restrições são permitidas:

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

É possível solicitar uma rota que evite qualquer combinação de pedágios, rodovias e balsas passando restrições para o parâmetro avoid. Por exemplo: avoid=tolls|highways|ferries.

Observação: a inclusão de restrições não exclui rotas que incluam a característica restrita; ela simplesmente direciona o resultado para rotas mais favoráveis.

Sistemas de unidades

Resultados da Directions API contêm text em campos distance que podem ser exibidos para o usuário para indicar a distância de uma "etapa" específica da rota. Por padrão, esse texto usa o sistema de unidade do país ou da região do local de origem.

Por exemplo, uma rota que parte de "Chicago, IL" para "Toronto, ONT" exibirá resultados em milhas, enquanto a rota inversa exibirá resultados em quilômetros. É possível modificar esse sistema de unidades configurando um explicitamente no parâmetro units da solicitação e passando um dos seguintes valores:

  • metric especifica o uso do sistema métrico. 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: a configuração do sistema de unidades afeta somente o text exibido nos campos distance. Os campos distance também contêm values sempre expressados em metros.

Direcionamento de região

Também é possível configurar o serviço da Directions API para retornar resultados direcionados a uma região específica usando o parâmetro region. Esse parâmetro aceita um argumento ccTLD (domínio de nível superior de código de país) especificando o direcionamento de região. 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 seu código ISO 3166-1 é "gb" (tecnicamente, para a entidade do "Reino Unido da Grã-Bretanha e da Irlanda do Norte").

Você pode usar qualquer domínio para o qual o aplicativo principal do Google Maps tenha lançado rotas de condução.

Por exemplo, uma solicitação de rota de "Toledo" para "Madri" retorna um resultado quando region é definido como es, pois "Toledo" é interpretado como uma cidade da Espanha:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Uma rota de "Toledo" a "Madrid" enviada sem um parâmetro region não retorna resultados, pois "Toledo" é interpretado como a cidade de Ohio:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Respostas de rotas

As respostas de rotas são retornadas no formato indicado pelo sinalizador output dentro do caminho da solicitação de URL.

Exemplos de respostas

Veja abaixo um exemplo de uma solicitação HTTP, calculando a rota de Chicago, IL a Los Angeles, CA, passando por dois pontos de referência em Joplin, MO e Oklahoma City, OK.

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

O exemplo acima solicita uma resposta em JSON. Também é possível solicitar respostas em XML. Clique nas guias abaixo para ver as respostas para os exemplos de JSON e XML.

Como as rotas podem ser extensas, elementos repetidos nas respostas são omitidos para torná-las mais claras.

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

Geralmente, apenas uma entrada da matriz routes é retornada para pesquisas de rota, mas o serviço da Directions API pode retornar diversas rotas se você passar alternatives=true.

Observe que esses resultados geralmente precisam ser analisados para que você possa extrair valores dos resultados. Analisar resultados em JSON é relativamente fácil. Consulte Analisar JSON para ver alguns padrões de projeto recomendados.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Observe que a resposta XML consiste em um único elemento <DirectionsResponse> e os seguintes elementos de nível superior:

  • <status> contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • Um <geocoded_waypoint> por ponto de referência, além da origem e do destino, com detalhes sobre o resultado da geocodificação desses elementos. A solicitação pode conter elementos <geocoded_waypoint/> vazios. Consulte Pontos de referência geocodificados abaixo.
  • Zero ou mais elementos <route>, cada um contendo um só conjunto de informações de rota entre a origem e o destino.

Recomendamos o uso de json como sinalizador de saída preferencial, a menos que seu serviço exija xml por algum motivo. O processamento de árvores XML exige certo cuidado para referenciar os nós e elementos corretos. Consulte Analisar XML com XPath para ver alguns padrões de projeto recomendados para o processamento da saída.

O restante deste documento usará a sintaxe JSON. Na maioria dos casos, o formato de saída não importa para os fins de demonstrar conceitos ou nomes de campos na documentação. Entretanto, observe as seguintes diferenças sutis:

  • Resultados XML são contidos em um elemento raiz <DirectionsResponse>.
  • JSON denota entradas com vários elementos por matriz de plural (como steps e legs), enquanto que XML denota usando vários elementos de singular (como <step> e <leg>).
  • JSON denota pontos de referência pelo campo waypoint_order, enquanto que XML denota usando elementos <waypoint_index> individuais.
  • Elementos em branco são indicados por matrizes em branco em JSON, mas pela falta desses elementos em XML. Por exemplo, uma resposta que não gera resultados retornará uma matriz routes vazia em JSON, mas nenhum elemento <route> em XML.

Elementos de resposta de rotas

As respostas da Directions API contêm os seguintes elementos raiz:

  • status contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • geocoded_waypoints contém uma matriz com detalhes sobre a geocodificação da origem, do destino e dos pontos de referência. Consulte Pontos de referência geocodificados abaixo.
  • routes contém uma matriz de rotas da origem ao destino. Consulte Rotas abaixo. Rotas consistem em trechos e etapas.
  • available_travel_modes contém uma matriz de modos de percurso disponíveis. Este campo é retornado quando uma solicitação especifica um mode de transporte e não recebe resultados. A matriz contém os modos de transporte disponíveis nos países do determinado conjunto de pontos de referência. Este campo não é retornado se um ou mais pontos de referência forem via:. Consulte os detalhes abaixo.

Códigos de status

O campo status dentro do objeto de resposta da Directions API contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo da falha do serviço da Directions API. O campo status pode conter os seguintes valores:

  • OK indica que a resposta contém um result válido.
  • NOT_FOUND indica que pelo menos uma das localizações especificadas na origem, no destino ou nos pontos de referência da solicitação não foram geocodificadas.
  • ZERO_RESULTS indica que não foi possível encontrar rotas entre a origem e o destino.
  • MAX_WAYPOINTS_EXCEEDED indica que foi fornecida uma quantidade excessiva de waypoints na solicitação. Para aplicativos que usam a Google Maps Directions API como um serviço da Web ou o serviço Directions na Google Maps JavaScript API, o número máximo permitido de waypoints é 23, mais a origem e o destino. Clientes Google Maps APIs Premium Plan podem enviar solicitações com até 23 pontos de referência, mais a origem e o destino.
  • INVALID_REQUEST indica que a solicitação fornecida é inválida. Causas comuns desse status incluem parâmetros ou valores de parâmetros inválidos.
  • OVER_QUERY_LIMIT indica que o serviço recebeu solicitações demais do seu aplicativo no intervalo de tempo permitido.
  • REQUEST_DENIED indica que o serviço negou o uso do serviço da Directions API por parte do seu aplicativo.
  • UNKNOWN_ERROR indica que uma solicitação da Directions API não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Mensagens de erro

Quando o código de status é diferente de OK, pode haver um campo error_message adicional no objeto de resposta de rota. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status.

Observação: não é garantido que esse campo esteja sempre presente e o conteúdo dele está sujeito a mudanças.

Pontos de referência geocodificados

Detalhes sobre a geocodificação de cada ponto de referência, além da origem e do destino, podem ser encontrados na matriz geocoded_waypoints (JSON). Eles podem ser usados para deduzir por que o serviço retornaria rotas inesperadas ou não retornaria resultados.

Os elementos da matriz geocoded_waypoints correspondem, de acordo com sua posição de base zero, à origem, aos pontos de referência na ordem especificada e ao destino. Cada elemento inclui os seguintes detalhes sobre a operação de geocodificação do ponto de referência correspondente:

  • geocoder_status indica o código de status resultante da operação de geocodificação. Esse campo pode conter os seguintes valores:
    • "OK" indica que nenhum erro ocorreu; o endereço foi analisado e pelo menos um código geográfico foi retornado.
    • ZERO_RESULTS indica que o código geográfico foi bem-sucedido, mas não retornou resultados. Isso poderá ocorrer se o geocodificador receber um address que não existe.
  • partial_match indica que o geocodificador não retornou uma correspondência exata para a solicitação original, mas conseguiu corresponder parte do endereço solicitado. Pode ser recomendável verificar se a solicitação original inclui erros de ortografia e/ou um endereço incompleto.

    Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade onde você passou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "21 Henr St, Bristol, UK" retornará uma correspondência parcial para Henry Street e Henrietta Street. Observe que, se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação poderá sugerir um endereço alternativo. Sugestões acionadas dessa maneira também serão marcadas como correspondências parciais.

  • place_id é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar o place_id de uma resposta da Google Place Autocomplete API para calcular rotas para uma empresa local. Consulte a visão geral de IDs de local.
  • types indica o tipo de endereço do resultado de geocodificação para calcular rotas. Os seguintes tipos são retornados:
    • street_address indica um endereço preciso.
    • route indica uma rota com nome (como "US 101").
    • intersection indica uma interseção, geralmente de duas vias importantes.
    • political indica uma entidade política. Normalmente, esse tipo indica um polígono de administração civil.
    • country indica a entidade política nacional e normalmente é o tipo de ordem mais elevada retornado pelo geocodificador.
    • administrative_area_level_1 indica uma entidade civil de primeira ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são estados. Nem todas as nações incluem esses níveis administrativos. Na maioria dos casos, nomes curtos para administrative_area_level_1 respeitarão quase que totalmente as subdivisões da ISO 3166-2 e outras normas amplamente divulgadas, porém isso não é garantido, já que os resultados da nossa geocodificação se baseiam em diversos sinais e dados de localização.
    • administrative_area_level_2 indica uma entidade civil de segunda ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são condados. Nem todos os países incluem esses níveis administrativos.
    • administrative_area_level_3 indica uma entidade civil de terceira ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
    • administrative_area_level_4 indica uma entidade civil de quarta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todas as nações incluem esses níveis administrativos.
    • administrative_area_level_5 indica uma entidade civil de quinta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
    • colloquial_area indica um nome alternativo comumente usado para a entidade.
    • locality indica uma entidade política de cidade ou município incorporada.
    • ward indica um tipo específico de localidade japonesa para facilitar a distinção entre vários componentes de localidades em um endereço no Japão.
    • sublocality indica uma entidade civil de primeira ordem abaixo da localidade. Algumas localizações podem receber um destes tipos adicionais: sublocality_level_1 a sublocality_level_5. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.
    • neighborhood indica um bairro com nome
    • premise indica um local com nome, geralmente um prédio ou um conjunto que prédios com um nome em comum
    • premise indica uma entidade de primeira ordem abaixo de um local com nome, geralmente um prédio dentro de um conjunto que prédios com um nome em comum
    • postal_code indica um código postal usado pelo serviço postal do país.
    • natural_feature indica uma característica natural proeminente.
    • airport indica um aeroporto.
    • park indica um parque com nome.
    • point_of_interest indica um ponto de interesse com nome. Normalmente, pontos de interesse são entidades locais que não se encaixam facilmente em outra categoria, como o Empire State Building ou a Estátua da Liberdade.

    Uma lista vazia indica que não há tipos conhecidos para um componente de endereço específico, por exemplo, Lieu-dit na França.

Esses detalhes não estarão presentes para os pontos de referência especificados como valores textuais de latitude/longitude se o serviço não retornar resultados. Isso ocorre porque esses pontos de referência são geocodificados inversamente apenas para obter o endereço representativo após encontrar uma rota. Um objeto JSON vazio ocupará os locais correspondentes na matriz geocoded_waypoints.

Rotas

Quando a Google Maps Directions API retorna resultados, ela os insere em uma matriz routes (JSON). Mesmo que o serviço não retorne resultados (como quando a origem e/ou o destino não existe), ele ainda retorna uma matriz routes vazia. Respostas XML consistem em zero ou mais elementos <route>.

Cada elemento da matriz routes contém um único resultado da origem e do destino especificados. Essa rota pode consistir em um ou mais legs dependendo da presença de pontos de referência. A rota também contém informações de direitos autorais e avisos que devem ser exibidas ao usuário juntamente com as rotas.

Cada rota do campo routes pode conter os seguintes campos:

  • summary contém uma breve descrição textual da rota, ideal para nomear e diferenciar a rota das alternativas.
  • legs[] contém uma matriz que inclui informações de um trecho da jornada entre dois locais da mesma rota. Será definido um trecho para cada ponto de referência ou destino especificado. Uma rota que não inclua pontos de referência conterá exatamente um trecho na matriz legs. Cada trecho consiste em uma série de steps. Consulte Trechos da rota abaixo.
  • waypoint_order (ou <waypoint_index> em XML) contém uma matriz que indica a ordem dos pontos de referência na rota calculada. Esses pontos de referência podem ser reordenados se a solicitação passa optimize:true no parâmetro waypoints.
  • overview_polyline contém um único objeto points que inclui uma representação de polilinha codificada da rota. Essa polilinha é um caminho aproximado (regularizado) da rota resultante.
  • bounds contém a caixa de limitação da porta de visualização do overview_polyline.
  • copyrights contém o texto de direitos autorais a ser exibido para a rota em questão. Você deve processar e exibir essas informações por conta própria.
  • warnings[] contém um conjunto de avisos que devem ser exibidos ao mostrar a rota em questão. Você deve processar e exibir esses avisos por conta própria.
  • fare: se presente, contém o total das passagens para essa rota. Essa propriedade é retornada somente para solicitações de transporte público e somente para rotas quando as informações de passagens estão disponíveis para todos os trechos do percurso. Essas informações incluem:
    • currency: um código de moeda ISO 4217 que indica a moeda da quantia.
    • value: o total de passagens na moeda especificada com o parâmetro acima.
    • text: o total de passagens formatado no idioma solicitado.

Veja abaixo um exemplo de informações de passagem para uma rota:

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

Trechos

Cada elemento da matriz legs especifica um trecho da jornada da origem ao destino na rota calculada. Rotas que não contêm pontos de referência terão um só "trecho", mas rotas que definem um ou mais pontos de referência terão um ou mais trechos, correspondendo aos trechos específicos da jornada.

Cada trecho dos campos legs pode conter os seguintes campos:

  • steps[] contém uma matriz de etapas denotando informações sobre cada etapa do trecho da jornada. Consulte Etapas da rota abaixo.
  • distance indica a distância total percorrida pelo trecho em questão como um campo que inclui os seguintes elementos:

    • value indica a distância em metros
    • text contém uma representação legível da distância, exibida nas unidades usadas na origem ou estabelecidas pelo parâmetro units da solicitação. Por exemplo, milhas e pés serão usados para origens nos Estados Unidos. Observe que, independentemente do sistema de unidades exibido como texto, o campo distance.value sempre contém um valor expressado em metros.

    Esses campos poderão estar ausentes se a distância for desconhecida.

  • duration indica a duração total do trecho em questão como um campo que inclui os seguintes elementos:

    • value indica a duração em segundos.
    • text contém uma representação legível da duração.

    Esses campos poderão estar ausentes se a duração for desconhecida.

  • duration_in_traffic indica a duração total do trecho em questão. Esse valor é uma estimativa do tempo no trânsito baseada nas condições de trânsito atuais e históricas. Consulte o parâmetro de solicitação traffic_model para verificar as opções que podem ser usadas para solicitar que o valor seja otimista, pessimista ou a melhor estimativa. A duração no trânsito é retornada somente se todas as seguintes condições forem verdadeiras:

    • A solicitação inclui uma chave de API válida ou um ID de cliente da Google Maps APIs Premium Plan e uma assinatura válidos.
    • A solicitação não inclui pontos de referência com parada. Se a solicitação inclui pontos de referência, devem ser prefixadas com via: para evitar paradas.
    • A solicitação é especifica para rotas de condução, ou seja, o parâmetro mode está definido como driving.
    • A solicitação inclui um parâmetro departure_time.
    • Há condições de trânsito disponíveis para a rota solicitada.

    duration_in_traffic contém os seguintes campos:

    • value indica a duração em segundos.
    • text contém uma representação legível da duração.
  • arrival_time contém uma estimativa do tempo de chegada para o trecho. Essa propriedade é retornada apenas para rotas de transporte público. O resultado é retornado como um objeto Time com três propriedades:
    • value é o tempo especificado como um objeto Date do JavaScript.
    • text é o tempo especificado como uma string. O tempo é exibido no fuso horário da parada do transporte público.
    • time_zone contém o fuso horário da estação. O valor é o nome do fuso horário conforme a definição do banco de dados de fusos horários da IANA. Por exemplo: "America/New_York".
  • departure_time contém uma estimativa do tempo de partida do trecho, especificada como um objeto Time. O departure_time só está disponível para rotas de transporte público.
  • start_location contém as coordenadas de latitude/longitude da origem do trecho. Como a Directions API calcula rotas entre locais usando a opção de transporte mais próxima (geralmente uma estrada) nos pontos de partida e chegada, start_location pode ser diferente da origem fornecida para o trecho se, por exemplo, não houver uma estrada próxima da origem.
  • end_location contém as coordenadas de latitude/longitude do destino definido para o trecho. Como a Google Maps Directions API calcula rotas entre locais usando a opção de transporte mais próxima (geralmente uma estrada) nos pontos de partida e chegada, end_location poderá ser diferente do destino fornecido para o trecho se, por exemplo, não houver uma estrada próxima do destino.
  • start_address contém o endereço legível (normalmente uma rua) resultante da geocodificação inversa do start_location do trecho.
  • end_address contém o endereço legível (normalmente uma rua) resultante da geocodificação inversa do end_location do trecho.

Etapas

Cada elemento da matriz steps define uma etapa da rota calculada. Uma etapa é a menor unidade de uma rota, descrevendo uma instrução específica da jornada. Por exemplo, “Vire à esquerda na W. 4th St." A etapa não só descreve a instrução, como também contém informações de distância e duração indicando como a etapa está relacionada à etapa seguinte. Por exemplo, uma etapa "Siga para I-80 West" pode conter uma duração de "37 milhas" e "40 minutos", indicando que a próxima etapa está a 37 milhas/40 minutos da presente etapa.

Ao usar a Google Maps Directions API para obter rotas de transporte público, a matriz steps incluirá detalhes adicionais na forma de uma matriz transit_details. Se a rota incluir diversos modos de transporte, instruções detalhadas serão fornecidas para etapas de caminhada ou condução na matriz steps interna. Por exemplo, uma etapa de caminhada incluirá instruções da localização de partida à de chegada: "Ande até Innes Ave & Fitch St". Essa etapa incluirá instruções detalhadas de caminha para a rota na matriz steps interna. Por exemplo: "Siga na direção noroeste", "Vire à esquerda no Arelious Walker" e "Vire à esquerda na Innes Ave".

Cada etapa dos campos steps pode conter os seguintes campos:

  • html_instructions contém instruções formatadas para a etapa, apresentadas como uma string de texto HTTP.
  • distance contém a distância percorrida na presente etapa até a próxima. Saiba mais sobre esse campo na seção Trechos da rota acima. Esse campo poderá ser indefinido se a distância for desconhecida.
  • duration contém o tempo normalmente necessário para executar a presente etapa até a próxima. Veja a descrição na seção Trechos da rota acima. Esse campo poderá ser indefinido se a duração for desconhecida.
  • start_location contém a localização do ponto de partida da etapa como um conjunto de campos lat e lng.
  • end_location contém a localização do ponto de chegada da etapa como um conjunto de campos lat e lng.
  • polyline contém um único objeto points que inclui uma representação de polilinha codificada da etapa. Essa polilinha é um caminho aproximado (suavizado) da etapa.
  • steps contém instruções detalhadas para etapas de caminhada ou condução em rotas de transporte público. Subetapas só são disponibilizadas quando travel_mode é definido como "transit". A matriz steps interna tem o mesmo tipo que steps.
  • transit_details contém informações específicas de transporte público. Esse campo é retornado somente quando travel_mode é definido como "transit". Consulte Detalhes de transporte público abaixo.

Detalhes de transporte público

Rotas de transporte público retornam informações adicionais que não são relevantes para outros modos de transporte. Essas propriedades adicionais são apresentadas pelo objeto transit_details e retornadas como um campo de um elemento da matriz steps[]. No objeto TransitDetails, é possível acessar informações adicionais sobre paradas, linhas e agências de transporte público.

Um objeto transit_details pode conter os seguintes campos:

  • arrival_stop e departure_stop contêm informações sobre paradas/estações dessa parte do percurso. Detalhes de parada podem incluir:
    • name o nome da estação/parada. Por exemplo: "Union Square".
    • location a localização da estação/parada, representada como um campo lat e lng.
  • arrival_time e departure_time contêm os tempos de partida e chegada do trecho em questão da jornada, especificados como as três propriedades a seguir:
    • text é o tempo especificado como uma string. O tempo é exibido no fuso horário da parada do transporte público.
    • value é o tempo especificado no formato Unix ou em segundos desde a meia-noite (UTC) de 1º de janeiro de 1970.
    • time_zone contém o fuso horário da estação. O valor é o nome do fuso horário conforme a definição do banco de dados de fusos horários da IANA. Por exemplo: "America/New_York".
  • headsign especifica a direção na qual você viaja nessa linha, conforme indicado no veículo ou na parada de partida. Essa parada é, com frequência, a estação terminal.
  • headway especifica o número esperado de segundos entre as partidas da mesma parada no horário atual. Por exemplo, com um valor de 600 para headway, você terá uma espera de 10 minutos se perder o ônibus.
  • num_stops contém o número de paradas da etapa, contando o ponto de chegada, mas não o de partida. Por exemplo, se a sua rota envolve partir da parada A, passar pelas paradas B e C para então chegar na parada D, num_stops retorna 3.
  • line contém informações sobre a linha de transporte público usada na etapa, podendo incluir as seguintes propriedades:
    • name contém o nome completo da linha. Por exemplo: "7 Avenue Express".
    • short_name contém o nome curto da linha. Normalmente, esse valor é um número de linha, como "M7" ou "355".
    • color contém a cor normalmente usada para as placas dessa linha. A cor será especificada como uma string hexadecimal, como: #FF0033.
    • agencies contém uma matriz de objetos TransitAgency, cada um fornecendo informações sobre a operadora da linha, incluindo as seguintes propriedades:
      • name contém o nome da agência de transporte público.
      • url contém o URL da agência.
      • phone contém o número de telefone da agência.

      Você deve exibir os nomes e os URLs das agências de transporte público apresentadas nos resultados do trajeto.

    • url contém o URL da linha, conforme as informações fornecidas pela agência de transporte público.
    • icon contém o URL do ícone associado à linha.
    • text_color contém a cor de texto normalmente usada para a sinalização da linha. A cor será especificada como uma string hexadecimal.
    • vehicle contém o tipo de veículo usado pela linha. Esse elemento pode incluir as seguintes propriedades:
      • name contém o nome do veículo da linha. Por exemplo: "Metrô".
      • type contém o tipo de veículo operado na linha. Consulte a documentação sobre tipo de veículo para obter uma lista completa dos valores permitidos.
      • icon contém o URL do ícone associado ao tipo de veículo.
      • local_icon contém o URL do ícone associado a esse tipo de veículo, tomando como base a sinalização de transporte local.

Tipo de veículo

A propriedade vehicle.type pode retornar qualquer um dos seguintes valores:

Valor Definição
RAIL Trem.
METRO_RAIL Metrô leve.
SUBWAY Metrô subterrâneo.
TRAM Bonde.
MONORAIL Monotrilho.
HEAVY_RAIL Trem pesado.
COMMUTER_TRAIN Trem suburbano.
HIGH_SPEED_TRAIN Trem de alta velocidade.
BUS Ônibus
INTERCITY_BUS Ônibus intermunicipal.
TROLLEYBUS Trole.
SHARE_TAXI Um transporte compartilhado é um veículo que pode deixar e coletar passageiros em qualquer ponto de sua rota.
FERRY Balsa.
CABLE_CAR Um veículo que opera por meio de um cabo, normalmente terrestre. Bondes aéreos podem ser do tipo GONDOLA_LIFT.
GONDOLA_LIFT Um bonde aéreo.
FUNICULAR Um veículo puxado por cabo em descidas acentuadas. Um funicular geralmente consiste em dois vagões que funcionam como contrapesos um para o outro.
OTHER Todos os demais veículos retornarão esse tipo.

Modos de transporte disponíveis

O campo de resposta available_travel_modes contém uma matriz de modos de transporte disponíveis. Este campo é retornado quando uma solicitação especifica um mode de transporte e não recebe resultados. A matriz contém os modos de transporte disponíveis nos países do determinado conjunto de pontos de referência que têm resultados. O campo não é retornado se os pontos de referência forem via:.

Por exemplo, teste esta solicitação:

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

Ela produz esta resposta:

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

O parâmetro sensor

Anteriormente, a Google Maps API exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.

Enviar comentários sobre…

Google Maps Directions API
Google Maps Directions API
Precisa de ajuda? Acesse nossa página de suporte.