Solicitação e resposta da API Distance Matrix

Introdução

Uma solicitação da Google Distance Matrix API apresenta a seguinte forma:

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

em que outputFormat pode ser um dos seguintes valores:

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

Alguns parâmetros são obrigatórios, outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). Todos os caracteres reservados (por exemplo, o sinal de adição "+") precisam ser codificados em URL. A lista de parâmetros e os valores possíveis estão enumerados abaixo.

Parâmetros obrigatórios

• destinos

  Um ou mais locais para usar como ponto final no cálculo da distância e do tempo de viagem. As opções do parâmetro "destinos" são as mesmas do parâmetro "origens".

• origens

  O ponto de partida para calcular a distância e o tempo de viagem. Você pode fornecer um ou mais locais separados pelo caractere de barra vertical (|), na forma de um ID de lugar, um endereço ou coordenadas de latitude/longitude:

  • ID de lugar: se você fornecer um ID de lugar, adicione o prefixo place_id:.
  • Endereço: se você transmitir um endereço, o serviço vai geocodificar a string e convertê-la em uma coordenada de latitude/longitude para calcular a distância. Essa coordenada pode ser diferente da retornada pela API Geocoding, por exemplo, a entrada de um edifício em vez do centro dele.
    Observação: é preferível usar IDs de lugar em vez de endereços ou coordenadas de latitude/longitude. O uso de coordenadas sempre resulta na fixação do ponto na via mais próxima a elas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma via que leve ao destino de forma rápida ou segura. Usar o endereço vai fornecer a distância até o centro do edifício, e não até uma entrada.
  • Coordenadas: se você transmitir coordenadas de latitude/longitude, elas serão alinhadas à via mais próxima. É preferível transmitir um ID de lugar. Se você transmitir coordenadas, verifique se não há espaço entre os valores de latitude e longitude.
  • Os Plus Codes precisam ser formatados como um código global ou um código composto. Formate os plus codes conforme mostrado aqui (os sinais de adição têm escape de URL para %2B e os espaços, para %20):
    • O código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9 é codificado como 849VCWC8%2BR9).
    • O código composto é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9 Mountain View, CA, USA é codificado como CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Polilinha codificada: como alternativa, você pode fornecer um conjunto codificado de coordenadas usando o algoritmo de polilinha codificada. Isso é particularmente útil se você tiver um grande número de pontos de origem, porque o URL é significativamente mais curto ao usar uma polilinha codificada.
    • As polilinhas codificadas precisam ser prefixadas com enc: e seguidas por dois pontos :. Por exemplo: origins=enc:gfo}EtohhU:
    • Também é possível incluir várias polilinhas codificadas, separadas pelo caractere de barra vertical |. Exemplo:

      origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
      

Parâmetros opcionais

• arrival_time

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

• evitar

  As distâncias podem ser calculadas aderindo a certas restrições. As 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 compatíveis:

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

  É possível solicitar um trajeto que evite qualquer combinação de pedágios, rodovias e balsas transmitindo as duas restrições ao parâmetro "avoid". Por exemplo: avoid=tolls|highways|ferries

  Observação: a adição de restrições não impede rotas que incluem o recurso restrito. Ela direciona o resultado para rotas mais favoráveis.

• departure_time

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

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

• language

  O idioma em que os resultados serão retornados.

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

• modo

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

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

• região

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

• traffic_model

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

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

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

• transit_mode

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

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

• transit_routing_preference

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

  • less_walking indica preferência por pouca caminhada no trajeto calculado.
  • fewer_transfers indica preferência por um número limitado de transferências no trajeto calculado.

• unidades

  Especifica o sistema de unidades a ser usado ao mostrar resultados.

  Observação: essa configuração do sistema de unidades afeta apenas o texto mostrado nos campos de distância. Os campos de distância também contêm valores sempre expressos em metros.

Exemplos de solicitações

Este exemplo usa coordenadas de latitude/longitude para especificar as coordenadas de destino:

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

Este exemplo usa plus codes para especificar as coordenadas de destino:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Informações de trânsito

As informações de tráfego são usadas quando todas as condições a seguir se aplicam (estas são as condições necessárias para receber o campo duration_in_traffic na resposta da Distance Matrix):

• O parâmetro mode de viagem é driving ou não está especificado (driving é o modo de viagem padrão).
• A solicitação inclui um parâmetro departure_time válido. O departure_time pode ser definido como a hora atual ou algum horário no futuro. Seu valor não pode estar no passado.

Opcionalmente, inclua o parâmetro traffic_model na solicitação para especificar as proposições a serem usadas ao calcular o tempo no trânsito.

O URL a seguir inicia uma solicitação da Distance Matrix para distâncias de carro entre Boston, MA ou Charlestown, MA, e Lexington, MA e Concord, MA. A solicitação inclui um horário de partida, atendendo a todos os requisitos para retornar o campo duration_in_traffic na resposta da matriz de distâncias.

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins
   
  
 

Modificadores de local

É possível usar modificadores de local para indicar como os motoristas devem se aproximar de um lugar específico. Use o modificador side_of_road para especificar qual lado da via usar ou um título para indicar a direção correta do trajeto.

Especificar que os trajetos calculados precisam passar por um lado específico da via

Ao especificar um local, você pode solicitar que a rota calculada passe pelo lado da via para onde o ponto de referência está direcionado usando o prefixo side_of_road:. Por exemplo, esta solicitação vai retornar a distância de uma rota longa para que o veículo termine no lado da via para onde o ponto de referência foi direcionado:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

Ao usar side_of_road: com polilinhas codificadas, o modificador é aplicado a todos os locais ao longo da polilinha. Por exemplo, os dois destinos nesta solicitação usam o parâmetro:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

O modificador side_of_road: só pode ser usado com esta restrição:

• O parâmetro mode de viagem é driving ou não está especificado (driving é o modo de viagem padrão).

Especificar que os trajetos calculados devem ter uma determinada direção

Ao especificar um local, você pode solicitar que o trajeto calculado passe por ele em uma direção específica. Esse cabeçalho é especificado com o prefixo heading=X:, em que X é um valor inteiro de grau entre 0 (inclusivo) e 360 (exclusivo). Uma direção de 0 indica Norte, 90 indica Leste e assim por diante no sentido horário. Por exemplo, nesta solicitação, a rota calculada vai para o leste da origem e faz um retorno em U:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

O modificador heading=X: só pode ser usado com estas restrições:

• O parâmetro mode de viagem é driving, bicycling ou não está especificado (driving é o modo de viagem padrão).
• O modificador side_of_road não foi especificado para o mesmo local.
• O local é especificado com um valor de latitude/longitude. Não é possível usar heading com endereços, IDs de lugar ou polilinhas codificadas.

Solicitações e respostas do Distance Matrix

Confira abaixo um exemplo de solicitação HTTP que pede distância e duração de Vancouver, Colúmbia Britânica, Canadá e de Seattle, Washington, EUA, para São Francisco, Califórnia, EUA e para Victoria, Colúmbia Britânica, Canadá.

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

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

Os resultados são retornados em linhas, e cada uma contém uma origem pareada com cada destino.

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km
   
  
 

DistanceMatrixResponse

DistanceMatrixStatus

Códigos de status retornados pelo serviço.

• OK indica que a resposta contém um resultado válido.
• INVALID_REQUEST indica que a solicitação fornecida era inválida.
• MAX_ELEMENTS_EXCEEDED indica que o produto de origens e destinos excede o limite por consulta.
• MAX_DIMENSIONS_EXCEEDED indica que o número de origens ou destinos excede o limite por consulta.
• OVER_DAILY_LIMIT indica uma destas opções:
  • A chave de API está ausente ou é inválida.
  • O faturamento não foi ativado na sua conta.
  • Um limite de uso definido pelo próprio usuário foi excedido.
  • A forma de pagamento fornecida não é mais válida (por exemplo, o cartão de crédito expirou).
• OVER_QUERY_LIMIT indica que o serviço recebeu solicitações em excesso do seu aplicativo no período permitido.
• REQUEST_DENIED indica que o uso do serviço Distance Matrix foi recusado para seu aplicativo.
• UNKNOWN_ERROR indica que não foi possível processar uma solicitação da Distance Matrix devido a um erro de servidor. Se você tentar novamente, a solicitação poderá dar certo.

DistanceMatrixRow

DistanceMatrixElement

Tarifa

A tarifa total do trajeto.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

DistanceMatrixElementStatus

• OK indica que a resposta contém um resultado válido.
• NOT_FOUND indica que não foi possível geocodificar a origem e/ou o destino deste par.
• ZERO_RESULTS indica que não foi possível encontrar nenhum trajeto entre a origem e o destino.
• MAX_ROUTE_LENGTH_EXCEEDED indica que o trajeto solicitado é muito longo e não pode ser processado.

TextValueObject

Um objeto que contém um valor numérico e a representação de texto formatada dele.