Pronto!

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

Ative a Google Maps Distance Matrix API

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

  1. Criar ou selecionar um projeto
  2. Ative a Google Maps Distance Matrix API
  3. Criar chaves apropriadas
Continuar

Guia do desenvolvedor

A Google Maps Distance Matrix API é um serviço que fornece a distância e o tempo de percurso para uma matriz de origens e destinos.

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. Os elementos por dia são calculados como a soma das consultas do lado do cliente e do lado do servidor.

Este documento é destinado a desenvolvedores que querem computar o tempo e a distância do percurso entre um número de pontos dentro dos 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

A Google Maps Distance Matrix API retorna informações baseadas na rota recomendada entre os pontos de partida e chegada, conforme calculado pela Google Maps API, consistindo em linhas de valores de duration e distance para cada par.

O serviço não retorna informações detalhadas de rota. É possível obter as informações de rota passando a origem e o destino desejados para a Google Maps Directions API.

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

Solicitações de Distance Matrix

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

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

onde outputFormat pode ser qualquer um dos seguintes valores:

  • json (recomendado) indica a saída em JavaScript Object Notation (JSON) ou
  • 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. Observe que diferentes navegadores, proxies e servidores podem ter outros limites de caracteres para 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 Distance Matrix API por HTTP, use:

http://maps.googleapis.com/maps/api/distancematrix/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 (&).

Parâmetros obrigatórios

  • origins — o ponto inicial do cálculo do tempo e da distância do percurso. É 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 gera o código geográfico da string e o converte em coordenadas de latitude/longitude para calcular a distância. 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.
      origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON
    • Se você passar coordenadas de latitude/longitude, elas serão usadas no estado em que se encontram para calcular a distância. Não insira espaços entre os valores de latitude e longitude.
      origins=41.43206,-81.38992|-33.86748,151.20699
    • 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.
      origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    • 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 origem, 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: origins=enc:gfo}EtohhU:
      • Também é possível incluir várias polilinhas codificadas, separadas pelo caractere de barra reta (|). Por exemplo: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
  • destinations — um ou mais locais para usar como o ponto final do cálculo do tempo e da distância do percurso. As opções para o parâmetro destinations são as mesmas do parâmetro origins, 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 Distance Matrix. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Os exemplos a seguir usam coordenadas de latitude/longitude para especificar as coordenadas de destino:

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY

O exemplo a seguir mostra a mesma solicitação usando uma polilinha codificada:

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

Parâmetros opcionais

  • mode (o padrão é driving) — especifica o modo de transporte a ser usado ao calcular a distância e o tempo de percurso. Valores válidos e outros detalhes sobre solicitações são especificados na seção Modos de transporte deste documento.
  • 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.
  • avoid — introduz restrições à rota. Valores válidos são especificados na seção Restrições deste documento. É permitido especificar apenas uma restrição.
  • units — especifica o sistema de unidades a ser usado ao expressar a distância como texto. Consulte a seção Sistemas de unidade deste documento para saber mais.
  • 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 — 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.

      Observação: solicitações da Distance Matrix que especificam departure_time quando mode=driving são limitadas a um máximo de 100 elementos por solicitação. O número de origens multiplicado pelo número de destinos define o número de elementos.

  • 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ó poderá ser especificado para solicitações cujo modo de transporte for driving e que incluir um valor de departure_time, mas somente se a solicitação 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.
  • transit_mode — especifica um ou mais modos de transporte preferenciais. Esse parâmetro só pode ser especificado para solicitações cujo mode é transit. 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 solicitações 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 solicitações cujo mode é transit. 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.

Modos de transporte

Para calcular distâncias, você pode especificar o modo de transporte a ser usado com o parâmetro mode. Por padrão, as distâncias são calculadas para o modo de condução. Os seguintes modos de transporte são permitidos:

  • driving (padrão) indica que a distância deve ser calculada usando a rede de estradas.
  • walking solicita o cálculo de distância para caminhadas por vias para pedestres e calçadas (quando disponíveis).
  • bicycling solicita o cálculo de distância para bicicleta por ciclovias e ruas preferencias (quando disponíveis).
  • transit solicita o cálculo de distância por rotas de transporte público (quando disponíveis). O valor só poderá ser especificado se a solicitação incluir uma chave de API ou um ID de cliente do Google Maps APIs Premium Plan. 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 nem ciclovias claras, portanto, essas respostas retornarão warnings no resultado, que devem ser exibidos ao usuário.

Restrições

As distâncias 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
  • avoid=indoor

* 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 Distance Matrix API contêm text em campos distance para indicar a distância da rota calculada. O sistema de unidades a ser usado pode ser especificado como:

  • units=metric (padrão) retorna distâncias em quilômetros e metros.
  • units=imperial retorna distâncias 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.

Respostas da Distance Matrix API

Respostas para consultas da Google Maps Distance Matrix API são retornadas no formato indicado pelo sinalizador output no caminho da solicitação do URL.

Dois exemplos de solicitações HTTP são mostrados a seguir, solicitando a distância e a duração de Vancouver (Colúmbia Britânica, Canadá) e Seattle (Washington, EUA) para São Francisco (Califórnia, EUA) e Victoria (Colúmbia Britânica, Canadá).

Esta solicitação demonstra o uso do sinalizador output de JSON:

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Esta solicitação demonstra o uso do sinalizador output de XML:

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Esta solicitação retorna quatro elementos (duas origens para dois destinos):

Vancouver para São Francisco Vancouver para Victoria
Seattle para São Francisco Seattle para Victoria

Os resultados são retornados em linhas, cada uma contendo uma origem pareada com cada destino.

Experimente! Clique aqui para enviar o exemplo de solicitação no navegador. Se você for solicitado a escolher um aplicativo para abrir o arquivo, selecione o navegador ou o editor de texto da sua preferência.

Clique nas guias abaixo para ver as respostas para os exemplos de JSON e XML.

JSON
{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

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
<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

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.

Elementos de resposta da Distance Matrix API

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

  • status contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • origin_addresses contém uma matriz de endereços retornados pela API a partir da sua solicitação original. Esses endereços são formatados pelo codificador geográfico e localizados de acordo com o parâmetro language passado com a solicitação.
  • destination_addresses contém uma matriz de endereços retornados pela API a partir da sua solicitação original. Assim como os valores de origin_addresses, esses endereços são localizados, se apropriado.
  • rows contém uma matriz de elements, que, por sua vez, contêm um elemento status, duration e distance.

Códigos de status

Os campos status dentro do objeto de resposta contêm o status da solicitação e podem incluir informações de depuração úteis. A Distance Matrix API retorna um campo de status de nível superior, com informações gerais sobre a solicitação, além de um campo de status para cada campo de elemento, com informações sobre o par específico de origem e destino.

Códigos de status de nível superior
  • OK indica que a resposta contém um result válido.
  • INVALID_REQUEST indica que a solicitação fornecida é inválida.
  • MAX_ELEMENTS_EXCEEDED indica que o produto das origens e dos destinos excedem o limite por consulta.
  • 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 Distance Matrix API por parte do seu aplicativo.
  • UNKNOWN_ERROR indica que uma solicitação da Distance Matrix API não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.
Códigos de status de nível de elemento
  • OK indica que a resposta contém um result válido.
  • NOT_FOUND indica que não foi possível geocodificar a origem e/ou o destino desse par.
  • ZERO_RESULTS indica que não foi possível encontrar rotas entre a origem e o destino.

Mensagens de erro

Quando o código de status de nível superior é diferente de OK, pode haver um campo error_message adicional no objeto de resposta da Distance Matrix API. 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.

Linhas

Quando a Google Maps Distance Matrix API retorna resultados, eles são colocados em uma matriz de rows JSON. Mesmo que nenhum resultado seja retornado (como quando as origens e/ou os destinos não existem), a API ainda retorna uma matriz vazia. Respostas XML consistem em zero ou mais elementos <row>.

As linhas são organizadas de acordo com os valores no parâmetro origin da solicitação. Cada linha corresponde a uma origem e cada elemento element da linha corresponde a um par de origem com um valor de destination.

Cada matriz de row contém uma ou mais entradas de element, que, por sua vez, contêm as informações de um só par de origem e destino.

Elementos

As informações sobre cada par de origem e destino são retornadas em uma entrada de element. Um element contém os seguintes campos:

  • status: consulte Códigos de status para obter uma lista de possíveis códigos de status.
  • duration: o tempo de percurso dessa rota, indicado em segundos (o campo value) e como text. A representação textual é localizada de acordo com o parâmetro language da consulta.
  • duration_in_traffic: o tempo de percurso dessa rota, baseado nas condições atuais e históricas do trânsito. 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 é expressada em segundos (o campo value) e como text. A representação textual é localizada de acordo com o parâmetro language da consulta. 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 APIs Premium Plan e uma assinatura válidos.
    • Há condições de trânsito disponíveis para a rota solicitada.
    • O parâmetro mode está definido como driving.
  • distance: a distância total dessa rota expressada em metros (value) e como text. O valor textual usa o sistema de unidades especificado com o parâmetro unit da solicitação original ou pela região da origem.
  • fare: se presente, contém o total das passagens para essa rota. Essa propriedade é retornada somente para solicitações de transporte público e quando os prestadores de serviços de transporte disponibilizam informações de passagens. 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 um element com informações de passagem:

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

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 Distance Matrix API
Google Maps Distance Matrix API
Precisa de ajuda? Acesse nossa página de suporte.