Pronto!

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

Ativar a Google Maps JavaScript API

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

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

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

O serviço não retorna informações detalhadas de rota. Informações sobre rotas, incluindo polilinhas e direções textuais, podem ser obtidas passando a origem e o destino desejados para o serviço Directions.

Primeiros passos

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

Para ver a lista de APIs ativadas:

  1. Acesse o Google API Console.
  2. Clique no botão Select a project, selecione o mesmo projeto que você criou para a Google Maps JavaScript API e clique em Open.
  3. Na lista de APIs do Painel, procure a Google Maps Distance Matrix API.
  4. Se achar a API na lista, está tudo pronto. Se não, ative-a:
    1. Na parte superior da tela, selecione ENABLE API para exibir a guia Library. É possível também selecionar Library no menu à esquerda.
    2. Procure a Google Maps Distance Matrix API e, em seguida, selecione-a na lista de resultados.
    3. Selecione ENABLE. Depois do fim do processo, Google Maps Distance Matrix API aparece na lista de APIs no Painel.

Políticas e limites de uso

Cotas

Os limites de uso a seguir são aplicados ao serviço Distance Matrix:

Observação: toda consulta enviada ao serviço Distance Matrix está limitada ao número de elementos permitidos, em que o número de origens multiplicado pelo número de destinos determina o número de elementos.

Uso do serviço Distance Matrix no Plano padrão

  • 2.500 elementos gratuitos por dia, calculados pela soma das consultas do cliente e do servidor; ativar cobrança para ter acesso a maiores cotas diárias, com custo de US$ 0,50 por mais 1.000 elementos, até 100.000 elementos por dia.
  • Máximo de 25 origens ou 25 destinos por solicitação.
  • Máximo de 100 elementos por solicitação.
  • Máximo de 100 elementos por segundo, calculados pela soma das consultas do cliente e do servidor.

Uso do serviço Distance Matrix no Plano premium

  • Cota diária compartilhada gratuita de 100.000 solicitações a cada 24 horas. Solicitações adicionais mediante compra anual de crédito das Maps APIs.
  • Máximo de 25 origens ou 25 destinos por solicitação.
  • Máximo de 625 elementos por solicitação. Observação: as solicitações que usam o parâmetro opcional departure_time quando mode=driving estão limitadas a 100 elementos por solicitação.
  • Ilimitada elementos do cliente por segundo por projeto. Observe que a API do servidor tem limite de 1.000 elementos por segundo.

Limite de taxa aplicado por sessão de usuário, independentemente de quantos usuários compartilham o projeto.

O limite de taxa por sessão impede o uso de serviços do lado do cliente para fazer solicitações em lote. Para fazer solicitações em lote, use o Google Maps Distance Matrix API Web Service.

Políticas

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

Solicitações de Distance Matrix

O acesso ao serviço Distance Matrix é assíncrono, pois a Google Maps API precisa chamar um servidor externo. Por isso, passe um método de retorno de chamada a ser executado na conclusão da solicitação para processar os resultados.

Acesse o serviço Distance Matrix no código usando o objeto google.maps.DistanceMatrixService. O método DistanceMatrixService.getDistanceMatrix() inicia uma solicitação ao serviço Distance Matrix, passando um literal de objeto DistanceMatrixRequest contendo as origens, os destinos e o modo de transporte, bem como um método de retorno de chamada 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.
}

Ver o exemplo (distance-matrix.html)

A DistanceMatrixRequest contém os seguintes campos:

  • origins (obrigatório) — uma matriz contendo uma ou mais strings de endereço, objetos google.maps.LatLng ou google.maps.Place usados como ponto de partida para se calcular distância e tempo.
  • destinations (obrigatório) — uma matriz contendo uma ou mais strings de endereço, objetos google.maps.LatLng ou google.maps.Place usados como ponto de chegada para se calcular distância e tempo.
  • travelMode (opcional) — o modo de transporte a ser usado no cálculo de rotas. Consulte a seção sobre modos de transporte.
  • transitOptions (opcional) — opções que só se aplicam 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 só se aplicam a solicitações em que travelMode é DRIVING. Os valores válidos são descritos na seção sobre opções de condução.
  • unitSystem (opcional) — o sistema de unidades a ser usado para exibir distâncias. Os valores aceitos são:
    • google.maps.UnitSystem.METRIC (padrão)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcional) — se true, as rotas entre origens e destinos são calculadas evitando rodovias sempre que possível.
  • avoidTolls (opcional) — se true, as rotas entre os pontos são calculadas usando rotas sem pedágio sempre que possível.

Modos de transporte

Você pode especificar o modo de transporte a ser usado no cálculo de tempos e distâncias. No momento, são permitidos os seguintes modos de transporte:

  • BICYCLING solicita rotas de bicicleta por ciclovias e ruas preferenciais (no momento, disponível apenas nos EUA e em algumas cidades do Canadá).
  • DRIVING (padrão) indica rotas de condução padrão pela rede rodoviária.
  • TRANSIT solicita rotas de transporte público. Essa opção só pode ser especificada se a solicitação inclui uma chave de API. Consulte a seção sobre opções de transporte público para obter as opções disponíveis para esse tipo de solicitação.
  • WALKING solicita rotas de caminhada por calçadas e vias de pedestres (se houver).

Opções de transporte público

No momento, o serviço de transporte público é "experimental". Implementaremos limites de utilização nessa fase para evitar uso abusivo da API. Mais à frente, implementaremos um limite de 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âncias variam entre modos de transporte. Nas solicitações de transporte público, as opções avoidHighways e avoidTolls são ignoradas. Especifique opções de rotas específicas para transporte público usando o literal de objeto TransitOptions.

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

O literal de 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. Se o horário de chegada é especificado, o horário de partida é ignorado.
  • departureTime (opcional) especifica o horário de partida desejado como um objeto Date. departureTime é ignorado se arrivalTime é especificado. Se nenhum valor é especificado para departureTime ou arrivalTime, o padrão é agora (ou seja, o horário atual).
  • modes (optional) é uma matriz contendo um ou mais literais de objeto TransitMode. Esse campo somente pode ser incluído em solicitações com chave de API. Cada TransitMode especifica um modo de transporte público preferencial. Os valores a seguir são permitidos:
    • BUS indica que a rota calculada deve dar preferência ao deslocamento por ônibus.
    • RAIL indica que a rota calculada deve dar preferência ao deslocamento por trem, bonde, VLT e metrô.
    • SUBWAY indica que a rota calculada deve dar preferência ao deslocamento por metrô.
    • TRAIN indica que a rota calculada deve dar preferência ao deslocamento por trem.
    • TRAM indica que a rota calculada deve dar preferência ao deslocamento por bonde.
  • routingPreference (opcional) especifica preferências para rotas de transporte público. Usando esse recurso, é possível polarizar as opções retornadas em vez de aceitar a melhor rota padrão escolhida pela API. Esse campo só poderá ser especificado se a solicitação contiver uma chave de API. Os valores a seguir são permitidos:
    • FEWER_TRANSFERS indica que a rota calculada deve dar preferência a uma quantidade limitada de baldeações.
    • LESS_WALKING indica que a rota calculada deve dar preferência a uma distância limitada de caminhada.

Opções de condução

Especifique opções de rota para rotas de condução usando o objeto DrivingOptions. Informe um ID de cliente da Google Maps APIs Premium Plan no carregamento da API para incluir um campo drivingOptions na DistanceMatrixRequest.

O objeto DrivingOptions contém os seguintes 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 como um objeto Date. O valor deve ser definido como o horário atual ou algum horário no futuro. Seu valor não deve estar no passado. (A API converte todas as datas para UTC para garantir o processamento consistente entre fusos horários.) Para clientes da Google Maps APIs Premium Plan, se departureTime é incluído na solicitação, a API retorna a melhor rota considerando as condições de trânsito esperadas no momento e inclui o tempo previsto no trânsito (duration_in_traffic) na resposta. Se o horário de partida não é especificado (ou seja, a solicitação não inclui drivingOptions), a rota retornada é normalmente uma boa rota sem considerar condições de trânsito.
  • trafficModel (opcional) especifica as suposições a serem usadas no cálculo do 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 padrão é best_guess. Os valores a seguir são permitidos:
    • best_guess (padrão) indica que o valor duration_in_traffic retornado deve ser a melhor estimativa de tempo do percurso, considerando o que se sabe sobre as condições de trânsito passadas e as informações em tempo real. As informações de trânsito em tempo real são mais importantes quando departureTime é mais próximo do horário atual.
    • 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.

Veja a seguir um exemplo de DistanceMatrixRequest para rotas de condução, 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 de Distance Matrix

Uma chamada bem-sucedida ao serviço Distance Matrix retorna um objeto DistanceMatrixResponse e um objeto DistanceMatrixStatus. Esses objetos são passados à função de retorno de chamada especificada na solicitação.

O objeto DistanceMatrixResponse contém informações sobre distância e duração para cada par de origem/destino para o qual foi possível calcular uma rota.

{
  "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 contendo as localizações passadas no campo origins da solicitação de matriz de distâncias. Os endereços são retornados formatados pelo geocodificador.
  • destinationAddresses é uma matriz contendo as localizações passadas no campo destinations, no formato retornado pelo geocodificador.
  • rows é uma matriz de objetos DistanceMatrixResponseRow, onde cada linha corresponde a uma origem.
  • elements são filhos de rows e correspondem a um pareamento da origem da linha com cada destino. Eles contêm status, duração, distância e informações de passagens (se disponíveis) para cada par origem/destino.
  • Cada element contém os campos a seguir:
    • 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. O valor textual é formatado de acordo com o unitSystem especificado na solicitação (ou no sistema métrico, se a preferência não foi informada).
    • duration_in_traffic: o tempo de percurso dessa rota, considerando as condições de trânsito atuais, indicado em segundos (o campo value) e como text. O valor textual é formatado de acordo com o unitSystem especificado na solicitação (ou no sistema métrico, se a preferência não foi informada). duration_in_traffic somente é retornada para clientes da Google Maps APIs Premium Plan quando dados de tráfego estão disponíveis, mode é definido como driving e departureTime é incluído como parte do campo distanceMatrixOptions na solicitação.
    • distance: a distância total dessa rota, indicada em metros (value) e como text. O valor textual é formatado de acordo com o unitSystem especificado na solicitação (ou no sistema métrico, se a preferência não foi informada).
    • fare: contém o total das passagens (ou seja, o custo total das tarifas) 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.

Códigos de status

A resposta da matriz de distância inclui um código de status para a resposta como um todo, bem como um status para cada elemento.

Códigos de status de resposta

Os códigos de status da DistanceMatrixResponse são passados no objeto DistanceMatrixStatus e incluem:

  • OK — a solicitação é válida. Esse status pode ser retornado mesmo se nenhuma rota foi encontrada entre as origens e os destinos. Consulte Códigos de status de elemento para obter informações sobre o status de elementos.
  • INVALID_REQUEST — a solicitação é inválida. Geralmente, o motivo é a falta de campos obrigatórios. Consulte a lista de campos permitidos acima.
  • MAX_ELEMENTS_EXCEEDED — o produto de origens e destinos excede o limite por consulta.
  • MAX_DIMENSIONS_EXCEEDED — a solicitação contém mais de 25 origens ou mais de 25 destinos.
  • OVER_QUERY_LIMIT — o aplicativo solicitou um número excessivo de elementos dentro do período permitido. A solicitação poderá ser bem-sucedida se você tentar novamente após um intervalo razoável.
  • REQUEST_DENIED — o serviço recusou o uso do serviço Distance Matrix por sua página.
  • UNKNOWN_ERROR — um erro de servidor impediu o processamento de uma solicitação de matriz de distâncias. 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 desse pareamento.
  • OK — a resposta contém um resultado válido.
  • ZERO_RESULTS — não foi possível encontrar rotas entre a origem e o destino.

Análise dos resultados

O objeto DistanceMatrixResponse contém uma row para cada origem passada na solicitação. Cada linha contém um campo element para cada pareamento dessa origem com os destinos informados.

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];
      }
    }
  }
}

Enviar comentários sobre…

Google Maps JavaScript API
Google Maps JavaScript API
Precisa de ajuda? Acesse nossa página de suporte.