Serviço Distance Matrix

Observação: bibliotecas do lado do servidor

Esta página descreve o serviço do lado do cliente disponível com a API Maps JavaScript. Se você quiser trabalhar com o serviço da Web do Google Maps no seu servidor, consulte o Cliente Node.js para serviços do Google Maps (link em inglês). A página no link também apresenta os clientes Java, Python e Go para serviços do Google Maps.

Visão geral

Consulte também a Referência da API Maps JavaScript: Distance Matrix

O serviço Distance Matrix do Google calcula a distância e a duração da viagem entre várias origens e destinos usando um determinado meio de transporte.

Ele não retorna informações detalhadas do trajeto. Informe a origem e o destino únicos desejados para o Directions Service e receba informações do trajeto, incluindo polilinhas e rotas textuais.

Como começar

Antes de usar o serviço Distance Matrix, verifique se a API de mesmo nome está ativada no console do Google Cloud, no mesmo projeto que você configurou para a API Maps JavaScript.

Para saber quais são as APIs ativadas:

1. Acesse o console do Google Cloud.
2. Clique no botão Selecionar um projeto, escolha aquele que você configurou para a API Maps JavaScript e clique em Abrir.
3. Na lista de APIs do Painel, procure a API Distance Matrix.
4. Se ela estiver na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
   1. Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral à esquerda.
   2. Procure e selecione API Distance Matrix na lista de resultados.
   3. Clique em ATIVAR. Ao término do processo, a API Distance Matrix aparece na lista de APIs do Painel.

Preços e políticas

Preços

Em 16 de julho de 2018, um novo plano de pagamento por utilização entrou em vigor para o Maps, o Routes e o Places. Consulte Utilização e faturamento da API Distance Matrix e saiba mais sobre os novos preços e limites de uso do serviço Distance Matrix do JavaScript.

Observação: as consultas enviadas ao serviço Distance Matrix são limitadas pelo número de elementos permitidos, definido como o número de origens multiplicado pelo número de destinos.

Políticas

O uso do serviço Distance Matrix precisa estar de acordo com as políticas descritas para a API Distance Matrix.

Solicitações do Distance Matrix

O acesso ao serviço Distance Matrix é assíncrono, já que a API Google Maps precisa chamar um servidor externo. Por esse motivo, para processar os resultados, você tem que transmitir um método de callback a ser executado na conclusão da solicitação.

Acesse o serviço Distance Matrix no seu código usando o objeto construtor google.maps.DistanceMatrixService. O método DistanceMatrixService.getDistanceMatrix() inicia uma solicitação ao serviço Distance Matrix, transmitindo um literal de objeto DistanceMatrixRequest que contém as origens, os destinos e o meio de transporte, além do método de callback para execução no recebimento da resposta.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Exemplo

DistanceMatrixRequest contém os seguintes campos:

• origins (obrigatório): uma matriz que contém uma ou mais strings de endereço, objetos google.maps.LatLng ou objetos do Places usados como origem para calcular a distância e o tempo.
• destinations (obrigatório): uma matriz que contém uma ou mais strings de endereço, objetos google.maps.LatLng ou objetos do Places usados como destino para calcular a distância e o tempo.
• travelMode (opcional): o meio de transporte a ser usado no cálculo de rotas. Consulte a seção sobre meios de transporte.
• transitOptions (opcional): opções usadas apenas para solicitações em que travelMode é TRANSIT. Os valores válidos estão disponíveis na seção sobre opções de transporte público.
• drivingOptions (opcional): especifica valores usados apenas para solicitações em que travelMode é DRIVING. Os valores válidos estão disponíveis na seção sobre opções de direção.
• unitSystem (opcional): o sistema de unidades a ser usado ao mostrar as distâncias. Os valores aceitos são:
  • google.maps.UnitSystem.METRIC (padrão)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (opcional): quando true, os trajetos calculados entre as origens e os destinos evitam rodovias sempre que possível.
• avoidTolls (opcional): quando true, as rotas calculadas entre os pontos usam trajetos sem pedágio sempre que possível.

Observação: o campo durationInTraffic foi descontinuado. Anteriormente, ele era usado para os clientes do Plano Premium da Plataforma Google Maps especificarem se as condições atuais de trânsito deveriam ser consideradas no resultado. Agora, use o campo drivingOptions.

Meios de transporte

Ao calcular tempos e distâncias, você pode especificar um dos meios de transporte que têm suporte no momento:

• BICYCLING solicita rotas de bicicleta por ciclovias e ruas preferenciais (disponível atualmente apenas nos EUA e em algumas cidades do Canadá).
• DRIVING (padrão), indica rotas de carro padrão usando a rede viária.
• TRANSIT solicita rotas por trajetos de transporte público. Só é possível especificar essa opção quando a solicitação inclui uma chave de API. Consulte na seção sobre opções de transporte público para saber quais estão disponíveis nesse tipo de solicitação.
• WALKING solicita rotas a pé por faixas de pedestre e calçadas (quando disponível).

Opções de transporte público

No momento, o serviço de transporte público ainda é experimental. Nesta fase, estamos implementando limites de taxa para evitar abuso da API. Futuramente, vamos impor um limite para o total de consultas por carregamento de mapa com base no uso normal da API.

As opções disponíveis para uma solicitação de matriz de distância variam entre meios de transporte. Nas solicitações de transporte público, as opções avoidHighways e avoidTolls são ignoradas. Use o literal do objeto TransitOptions se quiser definir opções de trajeto específicas para transporte público.

As solicitações de transporte público dependem do horário. Só são retornados cálculos para horários futuros.

O literal do objeto TransitOptions contém os seguintes campos:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Esses campos são explicados a seguir:

• arrivalTime (opcional) especifica o horário de chegada desejado como um objeto Date. O horário de partida é ignorado quando o de chegada é informado.
• departureTime (opcional) especifica o horário de partida desejado como um objeto Date. departureTime é ignorado quando arrivalTime é informado. Se não for especificado nenhum valor para departureTime ou arrivalTime, o valor padrão será o horário atual (agora).
• modes (opcional) é uma matriz que contém um ou mais literais de objeto TransitMode. Esse campo só é incluído em solicitações com uma chave de API. Cada TransitMode especifica um meio de transporte preferencial. Estes são os valores permitidos:
  • BUS indica preferência ao deslocamento por ônibus no trajeto calculado.
  • RAIL indica preferência ao deslocamento por trem, bonde, veículo leve sobre trilhos (VLT) e metrô 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.
• routingPreference (opcional) especifica preferências para trajetos por transporte público. Usando esse recurso, é possível direcionar as opções retornadas em vez de aceitar o melhor trajeto padrão escolhido pela API. Só é possível especificar esse campo quando a solicitação inclui uma chave de API. Estes são os valores permitidos:
  • FEWER_TRANSFERS indica preferência por um número limitado de transferências no trajeto calculado.
  • LESS_WALKING indica preferência por pouca caminhada no trajeto calculado.

Opções de condução

Use o objeto drivingOptions para especificar um horário de partida no cálculo do melhor trajeto até seu destino, considerando as condições de trânsito esperadas. Você também pode definir se prefere uma previsão pessimista, otimista ou a melhor estimativa para o tempo de percurso com base nas condições de trânsito históricas e em tempo real.

O objeto drivingOptions contém estes campos:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Esses campos são explicados a seguir:

• departureTime (obrigatório para que o literal de objeto drivingOptions seja válido) especifica o horário de partida desejado como um objeto Date. O valor precisa ser definido como o horário atual ou no futuro, nunca no passado. A API converte todas as datas para UTC, garantindo o processamento consistente entre fusos horários. Se você incluir o objeto departureTime na solicitação, a API vai retornar o melhor trajeto conforme as condições de trânsito esperadas no momento e incluir o tempo previsto no trânsito (duration_in_traffic) na resposta. Se não especificar um horário de partida (ou seja, a solicitação não inclui drivingOptions), será retornado um trajeto que normalmente é bom, sem considerar as condições de trânsito.

  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.

• trafficModel (opcional) especifica as premissas a serem usadas no cálculo do tempo em 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 padrão é best_guess. Estes são os valores permitidos:
  • bestguess (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 objeto departureTime, 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 exemplo de DistanceMatrixRequest abaixo mostra trajetos de carro, incluindo horário de partida e modelo de trânsito:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Respostas do Distance Matrix

Uma chamada bem-sucedida do serviço Distance Matrix retorna os objetos DistanceMatrixResponse e DistanceMatrixStatus. Eles são transmitidos à função de callback especificada na solicitação.

O objeto DistanceMatrixResponse contém informações de distância e duração para cada par origem/destino em que é possível calcular um trajeto.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Resultados do Distance Matrix

Estes são os campos permitidos em uma resposta.

• originAddresses é uma matriz que contém os locais transmitidos no campo origins da solicitação ao Distance Matrix. Os endereços são retornados formatados pelo geocodificador.
• destinationAddresses é uma matriz que contém os locais transmitidos no campo destinations, no formato retornado pelo geocodificador.
• rows é uma matriz de objetos DistanceMatrixResponseRow em que cada linha corresponde a uma origem.
• elements são secundários ao campo rows e correspondem a um par da origem da linha com cada destino. Eles contêm status, duração, distância e informações de tarifa (se disponíveis) para cada par origem/destino.
• Cada element contém os campos a seguir:
  • status: consulte uma lista dos valores possíveis em códigos de status.
  • duration: o tempo de viagem desse trajeto, expresso em segundos (campo value) e como text. O valor textual é formatado de acordo com o objeto unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência seja informada.
  • duration_in_traffic: o tempo de viagem desse trajeto considerando as condições de trânsito atuais, expresso em segundos (campo value) e como text. O valor textual é formatado de acordo com o objeto unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência seja informada. O valor de duration_in_traffic só é retornado aos clientes do Plano Premium da Plataforma Google Maps quando os dados de trânsito estão disponíveis, mode está definido como driving e departureTime faz parte do campo distanceMatrixOptions na solicitação.
  • distance: a distância total do trajeto, expressa em metros (value) e como text. O valor textual é formatado de acordo com o objeto unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência seja informada.
  • fare: 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. Estão incluídos:
    • currency: um código ISO 4217 que indica a moeda em que o valor é expresso.
    • value: o valor total das tarifas na moeda especificada acima.

Códigos de status

A resposta do serviço Distance Matrix inclui um código de status geral e um para cada elemento.

Códigos de status da resposta

Os códigos usados no objeto DistanceMatrixResponse são transmitidos em DistanceMatrixStatus e incluem:

• OK: a solicitação é válida. Esse status pode ser retornado mesmo que nenhum trajeto seja encontrado entre as origens e os destinos. Consulte as informações de status em códigos de status do elemento.
• INVALID_REQUEST: a solicitação fornecida era inválida. Geralmente, o motivo é a falta de campos obrigatórios. Consulte a lista de campos permitidos acima.
• MAX_ELEMENTS_EXCEEDED: o número de origens e destinos excede o limite por consulta.
• MAX_DIMENSIONS_EXCEEDED: a solicitação contém mais de 25 origens ou destinos.
• OVER_QUERY_LIMIT: o aplicativo solicitou elementos demais no período permitido. Tente novamente após um intervalo razoável.
• REQUEST_DENIED: o uso do serviço Distance Matrix foi recusado para sua página da Web.
• UNKNOWN_ERROR: não foi possível processar uma solicitação do Distance Matrix devido a um erro de servidor. Tente novamente.

Códigos de status de elementos

Os códigos a seguir são usados em objetos DistanceMatrixElement específicos:

• NOT_FOUND: não foi possível geocodificar a origem e/ou o destino deste par.
• OK: a resposta contém um resultado válido.
• ZERO_RESULTS: não foi possível encontrar nenhum trajeto entre a origem e o destino.

Analisar os resultados

O objeto DistanceMatrixResponse contém um row para cada origem que foi transmitida na solicitação. Todas as linhas contêm um campo element para cada par da origem com os destinos fornecidos.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}