A Google Maps Directions API

Introdução

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

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.

Você pode procurar rotas para diversos modos de transporte, incluindo transporte público, condução, caminhada ou bicicleta. As rotas podem especificar origens, destinos e pontos de referência como strings de texto (exemplo: "Chicago, IL" ou "Darwin, NT, Austrália") ou como coordenadas de latitude/longitude. A Directions API pode retornar rotas em várias partes usando uma série de pontos de referência.

Esse serviço geralmente tem como objetivo calcular rotas para endereços estáticos (já conhecidos) para inserir conteúdo do aplicativo em um mapa. Esse serviço não foi projetado para responder a consultas do usuário em tempo real, por exemplo. 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.

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.

Obter uma chave Limites de uso

Público-alvo

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.

Solicitações de rotas

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

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

onde output pode ser um dos seguintes valores:

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

Para acessar a Google Maps Directions API por HTTP, use:

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

é recomendável o uso de HTTPS para aplicativos que incluam dados confidenciais de usuários nas solicitações, como a localização.

Os URLs da Google Maps Directions API têm um limite aproximado de 2000 caracteres após a codificação do URL. Como alguns URLs da Google Maps Directions API podem envolver muitos locais ao longo de um caminho, esteja ciente desse limite ao gerar seus URLs.

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 como string, o serviço da Directions API gerará o código geográfico da string e a 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, 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.
  • 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 API for Work. É possível recuperá-lo 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.
• 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: usuários da Google Maps API for Work devem incluir parâmetros client e signature válidos em suas solicitações de rota. Consulte o capítulo Google Maps API for Work Web Services para saber mais.

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 coordenadas de latitude/longitude, como um ID de local ou como um endereço que será geocodificado. 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 API for Work. Pontos de referência são permitidos apenas para rotas de condução, caminhada e bicicleta. (Para saber mais sobre pontos de referência, consulte a seção Usar pontos de referência em rotas 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 API for Work receberão esse tipo de etapa por padrão.
  Para saber mais, consulte a seção Restrições de rota abaixo.
• language — especifica o idioma no qual retornar os resultados. Consulte a lista de idiomas de domínios suportados. Observe que atualizamos com frequência os idiomas suportados, portanto, essa lista pode não estar completa. Se language não for fornecido, o serviço tentará usar o idioma nativo do domínio de onde a solicitação for enviada.
• 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 API for Work 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 da Google Maps API for Work. 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.
• 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 da Google Maps API for Work. Os argumentos permitidos para esse parâmetro são:
  • 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 direcionar as opções retornadas em vez de aceitar a melhor rota padrão escolhida pela API. Ele só poderá ser especificado para rotas de transporte público cuja solicitação incluir uma chave de API ou um ID de cliente da Google Maps API for Work. Os argumentos permitidos para esse parâmetro são:
  • 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 (não estão disponíveis para 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.

Pontos de referência são especificados no parâmetro waypoints e consistem em um ou mais endereços ou locais separados pelo caractere de barra vertical (|).

Por exemplo, 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.

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.

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.

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

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

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 de matrizes plurais (steps), enquanto que XML denota entradas usando vários elementos singulares (<step>).
• 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.

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. A quantidade máxima de waypoints permitida é 23, além da origem e do destino. Se a solicitação não incluir uma chave de API, a quantidade máxima de waypoints permitidos será 8. Clientes da Google Maps API for Work podem enviar solicitações com até 23 pontos de referência.)
• 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 não foi possível processar uma solicitação de rotas 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.
  • 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 todas as nações 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 todas as nações 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 todas as nações 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 uma localização com nome, geralmente um prédio ou um conjunto de 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. É definido um trecho separado 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 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 (suavizado) 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 essa rota. Você deve processar e exibir essas informações por conta própria.
• warnings[] contém um conjunto de avisos a serem exibidos ao mostrar a rota. 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 um parâmetro departure_time.
  • A solicitação inclui uma chave de API válida ou um ID de cliente da Google Maps API for Work e uma assinatura válidos.
  • Há condições de trânsito disponíveis para a rota solicitada.
  • A solicitação não inclui pontos de referência com parada.
  • A solicitação é especifica para rotas de condução, ou seja, o parâmetro mode está definido como driving.

  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 quilômetros" e "40 minutos", indicando que a próxima etapa está a 37 quilômetros/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.

Tipo de veículo

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

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.