Serviço Distance Matrix

Visão geral

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 modo de transporte.

O serviço não retorna informações detalhadas de rota. As informações de trajeto, incluindo polilinhas e rotas textuais, podem ser recebidas passando a origem e o destino únicos desejados para o Serviço de rotas.

Primeiros passos

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

Para ver a lista de APIs ativadas:

  1. Acesse o Console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o mesmo projeto configurado para a API Maps JavaScript e clique em Abrir.
  3. Na lista de APIs do Painel, procure API Distance Matrix.
  4. Se achar a API na lista, está tudo pronto. Se a API não estiver listada, ative-a:
    1. Na parte superior da página, selecione ATIVAR API para exibir a guia Biblioteca. Como alternativa, no menu lateral à esquerda, selecione Biblioteca.
    2. Pesquise API Distance Matrix e selecione essa opção na lista de resultados.
    3. Selecione ATIVAR. Quando o processo for concluído, a API Distance Matrix aparecerá 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, Routes e Places. Para saber mais sobre os novos limites de preço e uso para o uso do serviço da JavaScript Distance Matrix, consulte Uso e faturamento da API Distance Matrix.

Observação: cada consulta enviada ao serviço Distance Matrix é limitada pelo número de elementos permitidos, em que o número de origens vezes o número de destinos define o número de elementos.

Limites de taxas

Observações sobre os limites de taxa em solicitações adicionais:

A limitação de taxa é aplicada por sessão de usuário, independentemente de quantos usuários compartilham o mesmo projeto. Ao carregar a API pela primeira vez, você recebe uma cota inicial de elementos. Depois de usar essa cota, a API aplica limites de taxa em outras solicitações por segundo. Se muitas solicitações forem feitas em um determinado período, a API retornará um código de resposta OVER_QUERY_LIMIT.

A limitação da taxa por sessão impede o uso de serviços do lado do cliente para solicitações em lote. Para solicitações em lote, use o serviço da Web da API Distance Matrix.

Políticas

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

Solicitações de Distance Matrix

O acesso ao serviço Distance Matrix é assíncrono porque a API Google Maps precisa fazer uma chamada para um servidor externo. Por isso, é necessário transmitir um método de callback para execução após a conclusão da solicitação e processar os resultados.

Para acessar o serviço Distance Matrix no seu código, use o objeto construtor google.maps.DistanceMatrixService. O método DistanceMatrixService.getDistanceMatrix() inicia uma solicitação para o serviço Distance Matrix, passando um literal de objeto DistanceMatrixRequest contendo as origens, os destinos e o modo de viagem, bem como um método de callback a ser executado 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.
}

Ver exemplo

O 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 Place a partir dos quais é possível calcular a distância e o tempo.
  • destinations (obrigatório): uma matriz contendo uma ou mais strings de endereço, objetos google.maps.LatLng ou objetos Place a que calcular distância e tempo.
  • travelMode (opcional): o meio de transporte a ser usado no cálculo de rotas. Consulte a seção sobre modos de viagem.
  • transitOptions (opcional): opções que se aplicam apenas a solicitações em que travelMode é TRANSIT. Os valores válidos são descritos na seção sobre opções de transporte público.
  • drivingOptions (opcional) especifica valores que se aplicam somente a solicitações em que travelMode é DRIVING. Os valores válidos são descritos na seção Opções de direção.
  • unitSystem (opcional) — o sistema de unidades a ser usado ao exibir a distância. Os valores aceitos são:
    • google.maps.UnitSystem.METRIC (padrão)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcional): se true, os trajetos entre as origens e os destinos serão calculados para evitar rodovias sempre que possível.
  • avoidTolls (opcional): se true, as rotas entre os pontos serão calculadas usando trajetos sem pedágio, sempre que possível.

Modos de transporte

Ao calcular tempos e distâncias, é possível especificar qual meio de transporte usar. Atualmente, os seguintes meios de transporte são suportados:

  • BICYCLING solicita rotas de bicicleta pelas ciclovias e ruas preferidas (atualmente disponível apenas nos EUA e em algumas cidades do Canadá).
  • DRIVING (padrão) indica rotas de carro padrão usando a rede rodoviária.
  • TRANSIT solicita rotas usando rotas de transporte público. Essa opção só poderá ser especificada se a solicitação incluir uma chave de API. Consulte a seção sobre opções de transporte público para ver as opções disponíveis nesse tipo de solicitação.
  • WALKING solicita rotas a pé com vias para pedestres e calçadas (quando disponível).

Opções de transporte público

Atualmente, o serviço de transporte público está em fase "experimental". Durante essa fase, implementaremos limites de taxa para evitar abusos de API. Em breve, vamos aplicar um limite de total de consultas por carregamento de mapa com base no uso aceitável da API.

As opções disponíveis para uma solicitação de matriz de distâncias variam entre modos de transporte. Em solicitações de transporte público, as opções avoidHighways e avoidTolls são ignoradas. É possível especificar opções de roteamento específicas de transporte público usando o literal de objeto TransitOptions.

As solicitações de transporte público dependem do horário. Os cálculos serão retornados apenas para horários no futuro.

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

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

Estes campos são explicados abaixo:

  • arrivalTime (opcional) especifica o horário desejado de chegada como um objeto Date. Se o horário de chegada for especificado, o horário de partida será ignorado.
  • departureTime (opcional) especifica o horário desejado de partida como um objeto Date. O departureTime será ignorado se arrivalTime for especificado. O padrão será agora (ou seja, o horário atual) se nenhum valor for especificado para departureTime ou arrivalTime.
  • modes (opcional) é uma matriz que contém um ou mais literais de objeto TransitMode. Este campo só poderá ser incluído se a solicitação incluir uma chave de API. Cada TransitMode especifica um meio de transporte público preferido. Os seguintes valores são permitidos:
    • BUS indica que o trajeto calculado precisa dar preferência ao transporte por ônibus.
    • RAIL indica que o trajeto calculado precisa dar preferência ao transporte por trem, bonde, veículo leve sobre trilhos (VLT) e metrô.
    • SUBWAY indica que o trajeto calculado deve preferir viajar de metrô.
    • TRAIN indica que o trajeto calculado deve preferir o deslocamento de trem.
    • TRAM indica que o trajeto calculado precisa dar preferência ao transporte por bonde e veículo leve sobre trilhos (VLT).
  • routingPreference (opcional) especifica preferências para trajetos de transporte público. Com essa opção, é possível polarizar as opções retornadas em vez de aceitar a melhor rota padrão escolhida pela API. Este campo só poderá ser especificado se a solicitação incluir uma chave de API. Os seguintes valores são permitidos:
    • FEWER_TRANSFERS indica que a rota calculada precisa preferir um número limitado de baldeações.
    • LESS_WALKING indica que o trajeto calculado precisa dar preferência a uma quantidade limitada de caminhadas.

Opções de condução

Use o objeto drivingOptions para especificar um horário de partida para calcular o melhor trajeto para seu destino, considerando as condições de trânsito esperadas. Também é possível especificar se você quer que o tempo estimado no tráfego seja pessimista, otimista ou a melhor estimativa com base nas condições históricas de trânsito e no tráfego em tempo real.

O objeto drivingOptions contém os seguintes campos:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Estes campos são explicados abaixo:

  • departureTime (obrigatório para que o literal de objeto drivingOptions seja válido) especifica o horário desejado de partida como um objeto Date. O valor precisa ser definido como a hora atual ou algum horário no futuro. Ele não pode estar no passado. A API converte todas as datas para UTC para garantir um tratamento consistente entre fusos horários. Se você incluir o departureTime na solicitação, a API retornará a melhor rota conforme as condições de tráfego esperadas no momento e incluirá o tempo previsto no tráfego (duration_in_traffic) na resposta. Se você não especificar um horário de partida, ou seja, se a solicitação não inclui drivingOptions, a rota retornada é uma boa rota sem considerar as condições de trânsito.

    Observação: se o horário de partida não for especificado, a opção de trajeto e duração vai ser baseada na rede rodoviária e nas condições médias de trânsito independentes de tempo. Os resultados de uma solicitação podem variar com o tempo devido a mudanças na malha rodoviária, nas condições médias de trânsito atualizadas e na natureza distribuída do serviço. Os resultados também podem variar entre rotas quase equivalentes a qualquer momento ou frequência.

  • trafficModel (opcional) especifica as suposições a serem usadas ao calcular o tempo no tráfego. Essa configuração afeta o valor retornado no campo duration_in_traffic na resposta, que contém o tempo previsto no tráfego com base nas médias históricas. O padrão é best_guess. Os seguintes valores são permitidos:
    • bestguess (padrão) indica que o duration_in_traffic retornado é a melhor estimativa do tempo de viagem, dado o que é conhecido sobre as condições históricas de trânsito e o trânsito em tempo real. O tráfego em tempo real se torna mais importante quando o departureTime está mais próximo do momento.
    • pessimistic indica que o duration_in_traffic retornado precisa ser maior que o tempo real de viagem na maioria dos dias, embora dias ocasionais com condições de trânsito particularmente ruins possam exceder esse valor.
    • optimistic indica que o duration_in_traffic retornado precisa ser menor que o tempo real de viagem na maioria dos dias, embora dias ocasionais com condições de trânsito particularmente boas possam ser mais rápidos do que esse valor.

Veja abaixo um exemplo de DistanceMatrixRequest para trajetos de carro, incluindo o horário de partida e o 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 de Distance Matrix

Uma chamada bem-sucedida para o serviço Distance Matrix retorna um objeto DistanceMatrixResponse e um objeto DistanceMatrixStatus. Elas são transmitidas para a função de retorno de chamada especificada na solicitação.

O objeto DistanceMatrixResponse contém informações de distância e duração para cada par de origem/destino para o qual uma rota pode ser calculada.

{
  "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 da matriz de distâncias

Os campos permitidos em uma resposta são explicados a seguir.

  • originAddresses é uma matriz que contém os locais transmitidos no campo origins da solicitação da 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, com cada linha correspondente a uma origem.
  • elements são filhos de rows e correspondem a um par da origem da linha com cada destino. Elas contêm o status, a duração, a distância e as informações de tarifa (se disponíveis) de cada par de origem/destino.
  • Cada element contém os seguintes campos:
    • status: consulte Códigos de status para ver uma lista dos possíveis códigos de status.
    • duration: o tempo de viagem dessa rota, expresso em segundos (o campo value) e como text. O valor textual é formatado de acordo com o unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência tenha sido fornecida.
    • duration_in_traffic: o tempo de viagem dessa rota considerando as condições de tráfego atuais, expressa em segundos (o campo value) e como text. O valor textual é formatado de acordo com o unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência tenha sido fornecida. O duration_in_traffic só é retornado aos clientes do plano Premium da Plataforma Google Maps quando os dados de tráfego estão disponíveis, o mode é definido como driving e o departureTime é incluído como 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 unitSystem especificado na solicitação ou na métrica, caso nenhuma preferência tenha sido fornecida.
    • fare: contém a tarifa total (ou seja, o total das despesas das passagens) no trajeto. Essa propriedade é retornada somente para solicitações de transporte público e apenas para provedores de transporte público em que as informações de tarifa estão disponíveis. As informações incluem:
      • currency: um código de moeda ISO 4217 indicando a moeda em que o valor é expresso.
      • value: o valor total da tarifa, na moeda especificada acima.

Códigos de status

A resposta da Distance Matrix inclui um código de status para a resposta como um todo e um status para cada elemento.

Códigos de status de resposta

Os códigos de status que se aplicam a DistanceMatrixResponse são transmitidos no objeto DistanceMatrixStatus e incluem:

  • OK: a solicitação é válida. Esse status pode ser retornado mesmo se nenhuma rota tiver sido encontrada entre as origens e os destinos. Consulte os códigos de status do elemento para ver as informações de status no nível do elemento.
  • INVALID_REQUEST: a solicitação fornecida era inválida. Geralmente, o motivo é a falta de campos obrigatórios. Veja a lista de campos compatíveis acima.
  • MAX_ELEMENTS_EXCEEDED: o produto das origens e destinos excede o limite por consulta.
  • MAX_DIMENSIONS_EXCEEDED: sua solicitação contém mais de 25 origens ou mais de 25 destinos.
  • OVER_QUERY_LIMIT: seu aplicativo solicitou muitos elementos dentro do período permitido. A solicitação vai ser bem-sucedida se você tentar novamente após um período razoável.
  • REQUEST_DENIED: o serviço negou o uso do serviço da Distance Matrix para sua página da Web.
  • UNKNOWN_ERROR: não foi possível processar uma solicitação da Distance Matrix devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Códigos de status de elementos

Os códigos de status a seguir se aplicam a 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: nenhuma rota pode ser encontrada entre a origem e o destino.

Análise dos resultados

O objeto DistanceMatrixResponse contém um row para cada origem que é transmitida na solicitação. Cada linha contém um campo element para cada par dessa 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];
      }
    }
  }
}