Solicitação e resposta da API Distance Matrix (legada)

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

Introdução

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

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 a 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 de chegada para calcular a distância e o tempo de viagem. As opções para o parâmetro de destinos são as mesmas do parâmetro de origens.

  • origens

    O ponto de partida para calcular a distância e o tempo de deslocamento. 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, ele precisará ter 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 no ajuste do ponto à via mais próxima delas, 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. O uso do endereço vai fornecer a distância até o centro do edifício, em vez de uma entrada para o edifício.
    • Coordenadas: se você transmitir coordenadas de latitude/longitude, elas serão ajustadas à 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 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 é útil principalmente 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 preferencial para rotas de transporte público, em segundos desde a meia-noite de 1º de janeiro de 1970 UTC. É possível especificar departure_time ou arrival_time, mas não ambos. arrival_time precisa ser especificado como um número inteiro.

  • evitar

    As distâncias podem ser calculadas aderindo a certas restrições. As restrições são indicadas pelo uso do parâmetro avoid e por um argumento para esse parâmetro que indica a restrição a ser evitada. As seguintes restrições são aceitas:

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

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

    Observação: a adição de restrições não impede trajetos que incluam o recurso restrito, mas influencia o resultado para trajetos mais favoráveis.

  • departure_time

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

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

  • language

    O idioma em que os resultados serão retornados.

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

  • modo

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

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

  • região

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

  • traffic_model

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

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

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

  • transit_mode

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

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

  • transit_routing_preference

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

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

  • unidades

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

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

Exemplos de solicitação

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

URL

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

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'

Neste exemplo, usamos Plus Codes para especificar as coordenadas de destino:

URL

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

curl

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:

URL

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

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 sobre o 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 matriz de distância:

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

Se quiser, inclua o parâmetro traffic_model na solicitação para especificar as premissas a serem usadas no cálculo do tempo em trânsito.

O URL a seguir inicia uma solicitação da matriz de distância 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ância.

URL

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

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'

JSON

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

XML


 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

Você pode usar modificadores de local para indicar como os motoristas devem se aproximar de um determinado local, usando o modificador side_of_road para especificar qual lado da via usar ou especificando um rumo para indicar a direção correta da viagem.

Especificar que as rotas calculadas precisam passar por um lado específico da via

Ao especificar um local, você pode solicitar que o trajeto calculado passe pelo lado da via em que o waypoint está usando o prefixo side_of_road:. Por exemplo, esta solicitação vai retornar a distância de um trajeto longo para que o veículo termine no lado da via para o qual o waypoint foi direcionado:

URL

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

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 cada local ao longo da polilinha. Por exemplo, os dois destinos nesta solicitação usam o parâmetro:

URL

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

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:

Especificar que os trajetos calculados devem ter uma direção específica

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 de grau inteiro entre 0 (inclusive) e 360 (exclusive). Uma direção de 0 indica o norte, 90 indica o leste, continuando no sentido horário. Por exemplo, nesta solicitação, o trajeto calculado vai para o leste a partir da origem e, em seguida, faz um retorno:

URL

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

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 de viagem mode é 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 da matriz de distância

Veja abaixo um exemplo de solicitação HTTP que pede a distância e a duração de Vancouver, BC, Canadá, e de Seattle, WA, EUA, até San Francisco, CA, EUA, e Victoria, BC, Canadá.

URL

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

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

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.

JSON

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

XML


 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

Campo Obrigatório Tipo Descrição
required Array<string>

Uma matriz de endereços retornada pela API da sua solicitação original. Assim como em origin_addresses, eles são localizados, se apropriado. O conteúdo precisa ser lido no estado em que se encontra. Não analise os endereços formatados de maneira programática.

required Array<string>

Uma matriz de endereços retornada pela API da sua solicitação original. Eles são formatados pelo geocodificador e localizados de acordo com o parâmetro de idioma transmitido com a solicitação. O conteúdo precisa ser lido no estado em que se encontra. Não analise os endereços formatados de maneira programática.

required Array<DistanceMatrixRow>

Uma matriz de elementos, cada um contendo um elemento status, duration e distance.

Consulte DistanceMatrixRow para mais informações.

required DistanceMatrixStatus

Contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo da falha da solicitação.

Consulte DistanceMatrixStatus para mais informações.

opcional string

Uma string que contém o texto legível por humanos de todos os erros encontrados enquanto a solicitação estava sendo processada.

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 número 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 qualquer uma das seguintes 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 dentro do período permitido.
  • REQUEST_DENIED indica que o uso do serviço Matriz de Distância foi recusado para seu aplicativo.
  • UNKNOWN_ERROR indica que não foi possível processar uma solicitação da matriz de distância devido a um erro de servidor. Se você tentar novamente, a solicitação poderá dar certo.

DistanceMatrixRow

Campo Obrigatório Tipo Descrição
required Array<DistanceMatrixElement>

Quando a API Distance Matrix retorna resultados, ela os coloca em uma matriz de linhas JSON. Mesmo que nenhum resultado seja retornado (como quando as origens e/ou os destinos não existem), ela ainda retorna uma matriz vazia.

As linhas são ordenadas de acordo com os valores no parâmetro de origem da solicitação. Cada linha corresponde a uma origem, e cada elemento nessa linha corresponde a um par da origem com um valor de destino.

Cada matriz de linha contém uma ou mais entradas de elemento, que, por sua vez, contêm as informações sobre um único par de origem-destino.

Consulte DistanceMatrixElement para mais informações.

DistanceMatrixElement

Campo Obrigatório Tipo Descrição
required DistanceMatrixElementStatus

Um status para o elemento.

Consulte DistanceMatrixElementStatus para mais informações.

opcional TextValueObject

A distância total do trajeto, expressa em metros (valor) e como texto. O valor textual usa o sistema de unidades especificado com o parâmetro unit da solicitação original ou a região de origem.

Consulte TextValueObject para mais informações.

opcional TextValueObject

O tempo de viagem desse trajeto, expresso em segundos (campo de valor) e como texto. A representação textual é localizada de acordo com o parâmetro de idioma da consulta.

Consulte TextValueObject para mais informações.

opcional TextValueObject

O tempo necessário para percorrer esse trajeto, com base nas condições de trânsito atuais e históricas. Consulte o parâmetro de solicitação traffic_model para ver as opções que podem ser usadas para solicitar que o valor retornado seja otimista, pessimista ou uma estimativa aproximada. A duração é expressa em segundos (o campo de valor) e como texto. A representação textual é localizada de acordo com o parâmetro de idioma da consulta. A duração no trânsito será retornada somente se todas as condições a seguir forem verdadeiras:

  • A solicitação inclui um parâmetro departure_time.
  • Há condições de trânsito disponíveis para o trajeto solicitado.
  • O parâmetro mode está definido como driving.

Consulte TextValueObject para mais informações.

opcional Tarifa

Se presente, contém a tarifa total (ou seja, o custo total das passagens) para esse trajeto. Essa propriedade só é retornada para solicitações de transporte público e prestadores que disponibilizam informações de tarifas.

Consulte Tarifa para mais informações.

Tarifa

A tarifa total do trajeto.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
Campo Obrigatório Tipo Descrição
required string

Um código de moeda ISO 4217 que indica a moeda em que o valor é expresso.

text

required string

o total de passagens formatado no idioma solicitado.
required número

O valor total das tarifas na moeda especificada.

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

Campo Obrigatório Tipo Descrição

text

required string

Valor da string.
required número

Valor numérico.