introdução

a matriz de distância API é um serviço que fornece distância de viagem e tempo para uma matriz de origens e destinos. A API devolve informações baseadas na rota recomendada entre os pontos de partida e de chegada, calculada pela API do Google Maps, e consiste em linhas contendo valores duration e distance para cada par.Nota: Este serviço não devolve informações pormenorizadas sobre a rota. A informação do percurso pode ser obtida passando a origem e o destino únicos desejados para as instruções API.

Antes de iniciar

Este documento destina-se a programadores que pretendam calcular a distância de viagem e o tempo entre vários pontos dentro dos mapas fornecidos por uma das APIs do Google Maps. Ele fornece uma introdução ao uso da API e material de referência sobre os parâmetros disponíveis.

Antes de começar a desenvolver com a API da matriz de distância, reveja os requisitos de autenticação (você precisa de uma chave de API) e a informação de utilização e faturação da API (você precisa para ativar a faturação em seu projeto).

Matriz de Distância de pedidos

Uma Matriz de Distância de solicitação de API, assume a seguinte forma:

, onde outputFormat pode ser qualquer um dos valores a seguir:

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

Nota: Os URLs devem ser devidamente codificados para serem válidos e estão limitados a 8192 caracteres para todos os serviços web. Esteja ciente deste limite ao construir seus URLs. Note que diferentes navegadores, proxies e servidores podem ter diferentes limites de caracteres de URL também.

HTTPS ou HTTP

segurança é importante e HTTPS é recomendado sempre que possível, especialmente para aplicações que incluem dados sensíveis do usuário, como a localização de um usuário, em solicitações. Usar a encriptação HTTPS torna a sua aplicação mais segura e mais resistente a bisbilhotar ou adulterar.

Se HTTPS não for possível, para acessar a API da matriz de distância sobre HTTP, use:

Request parameters

Certain parameters are required while others are optional. Como é padrão em URLs, todos os parâmetros são separados usando o caráter ampersand (&). Todos os caracteres reservados (por exemplo, o sinal mais “+”) devem ser codificados em URL.A lista de parâmetros e seus valores possíveis são enumerados abaixo.

parâmetros requeridos

• origins — o ponto de partida para o cálculo da distância e do tempo de viagem. Você pode fornecer um ou mais locais separados pelo caractere de pipe (|), na forma de um lugar de IDENTIFICAÇÃO, endereço ou coordenadas de latitude/longitude:
  • Se você fornecer um lugar de IDENTIFICAÇÃO, você deve prefixar-o com place_id:. Você só pode especificar um ID de lugar se o pedido incluir uma chave de API ou um ID de cliente de plano Premium da plataforma do Google Maps. Pode obter os IDs dos locais da API de Geocoding e da API dos locais (incluindo a auto-completação do local). Por exemplo, usando IDs de lugar a partir de lugar Auto-completo, veja o lugar Auto-completo e direções. Para mais informações sobre os IDs do local, consulte a visão geral do ID do local.
  • Se passar por um endereço, o serviço Geocode a cadeia de caracteres e converte-a numa coordenada de latitude/longitude para calcular a distância. Esta coordenada pode ser diferente da devolvida pela API Geocoding, por exemplo uma entrada de edifício em vez de seu centro.

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

    Nota: o uso de IDs de lugar é preferido ao uso de endereços ou coordenadas de latitude/longitude. A utilização de coordenadas resultará sempre em que o ponto seja desviado para a estrada mais próxima dessas coordenadas – o que pode não ser um ponto de acesso à propriedade, ou mesmo uma estrada que levará rápida ou seguramente ao destino.se passar as coordenadas de latitude/longitude, elas irão para a estrada mais próxima. É preferível passar uma identificação local. Se passar as coordenadas, certifique-se de que não existe espaço entre os valores de latitude e longitude.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus codes must be formatted as a global code or a compound code. O formato mais códigos, como mostrado aqui (sinais de adição url de escape para %2B e espaços url de escape para %20):
    • global código de 4 caracteres código de área e 6 ou mais caracteres de código local (849VCWC8+R9 é 849VCWC8%2BR9).
    • código composto é um código local de 6 caracteres ou mais longo com uma localização explícita (CWC8+R9 Mountain View, CA, EUA é CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativamente, você pode fornecer um conjunto codificado de coordenadas usando o algoritmo codificado Polyline. Isto é particularmente útil se você tiver um grande número de pontos de origem, porque a URL é significativamente mais Curta ao usar uma linha de código.
    • as polilinas codificadas devem ser prefixadas com enc:e seguidas por um cólon (:).Por exemplo: origins=enc:gfo}EtohhU:
    • Pode também incluir múltiplas polilinas codificadas, separadas pelo caracter do tubo (|). Por exemplo: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

  destinations — um ou mais locais a utilizar como ponto de chegada para calcular a distância e o tempo de viagem. As opções para o parâmetro destinations são as mesmas que para o parâmetro origins, descrito acima.

  • key — a chave API da sua aplicação. Esta chave identifica o seu pedido para efeitos de gestão de quotas. Aprende a arranjar uma chave. Nota: Os clientes do plano Premium da plataforma do Google Maps podem utilizar uma chave API ou um ID de cliente válido e uma assinatura digital, nos seus pedidos de matriz de distância. Obtenha mais informações sobre os parâmetros de autenticação para os clientes Premium Plan.

  O exemplo a seguir usa coordenadas de latitude/longitude para especificar o destino de coordenadas:

  O exemplo a seguir usa mais códigos para especificar o destino de coordenadas:

  O exemplo a seguir mostra o mesmo pedido usando uma polilinha codificada:

  parâmetros Opcionais

  • mode (padrão driving) — Especifica o modo de transporte a utilizar, ao calcular a distância. Os valores válidos e outros detalhes do pedido são especificados na secção modos de viagem do presente documento.
  • language — a língua na qual se deve devolver os resultados.
    • veja a lista de línguas suportadas. O Google frequentemente atualiza as línguas suportadas, de modo que esta lista pode não ser exaustiva.
    • Se language não é fornecido, a API tenta usar o idioma de preferência, conforme especificado no Accept-Language cabeçalho, ou no idioma nativo do domínio a partir do qual o pedido é enviado.
    • a API faz o seu melhor para fornecer um endereço de rua que é legível tanto para o Usuário e locais. Para alcançar esse objetivo, ele retorna endereços de rua na língua local, transliterado para um script legível pelo Usuário, se necessário, observando o idioma preferido. Todos os outros endereços são devolvidos na língua preferida. Os componentes do endereço são todos devolvidos na mesma língua, que é escolhida a partir do primeiro componente.
    • Se um nome não estiver disponível na língua preferida, a API usa a correspondência mais próxima.
    • a linguagem preferida tem uma pequena influência sobre o conjunto de resultados que a API escolhe retornar, e a ordem em que eles são devolvidos. O geocoder interpreta abreviaturas de forma diferente dependendo da linguagem, tais como as abreviaturas para tipos de rua, ou sinônimos que podem ser válidos em uma língua, mas não em outra. Por exemplo, utca e tér são sinônimos para street em Húngaro.
  • region — código da região, especificado como um valor de dois caracteres para o ccTLD (domínio de topo do Código do país). A maioria dos códigos ccTLD são idênticos aos códigos ISO 3166-1, com algumas excepções. Este parâmetro influenciará apenas, não restringindo totalmente, os resultados do geocoder. Se existirem resultados mais relevantes fora da região especificada, podem ser incluídos.
  • avoid — introduz restrições à rota. Os valores válidos são especificados na secção restrições do presente documento. Apenas uma restrição pode ser especificada.
  • units — especifica o sistema de unidades a usar ao expressar a distância como texto. Veja a seção de Sistemas de unidades deste documento para mais informações.
  • arrival_time — especifica a hora desejada de chegada para pedidos de trânsito, em segundos desde a meia-noite, 1 de janeiro de 1970 UTC. Você pode especificar tanto departure_time ou arrival_time, mas não ambos. Note que arrival_time deve ser especificado como um inteiro.
  • departure_time — a hora desejada de partida. Você pode especificar o tempo como um inteiro em segundos desde a meia-noite, 1 de janeiro de 1970 UTC. Se um departure_time depois de 9999-12-31T23:59:59.999999999 Z é especificado, a API retornará o departure_time 9999-12-31T23:59:59.999999999 Z. como Alternativa, você pode especificar um valor de now, que define o horário de partida para o tempo atual (correta para o segundo mais próximo). A hora de partida pode ser especificada em dois casos:
    • Para Os pedidos em que o modo de viagem é trânsito: Pode indicar opcionalmente um de departure_time ou arrival_time. Se nenhuma das Horas for especificada, o departure_time corresponde agora (isto é, a hora de partida corresponde à hora actual).
    • Para pedidos em que o modo de viagem é de condução: Você pode especificar o departure_time para receber um percurso e a duração da viagem (campo de resposta: duration_in_traffic) que tome as condições de tráfego em conta. Esta opção só está disponível se o pedido contiver uma chave API válida, ou uma assinatura e ID do cliente do Plano Premium da plataforma do Google Maps válida. O departure_time deve ser definido para o tempo atual ou algum tempo no futuro. Não pode ser no passado. Nota: Se a hora de partida não for especificada, a escolha do itinerário e da duração baseia-se na rede rodoviária e nas condições de tráfego independentes em termos de tempo médio. Os resultados de um determinado pedido podem variar ao longo do tempo devido a alterações na rede rodoviária, a condições de tráfego médias actualizadas e à natureza distribuída do serviço. Os resultados também podem variar entre rotas quase equivalentes a qualquer momento ou frequência.

      Nota: pedidos de matriz de distância especificando departure_timequandomode=driving estão limitados a um máximo de 100 elementos por pedido. O número de origens vezes o número de destinos define o número de elementos.

  • traffic_model (valores por omissão para best_guess) — especifica os pressupostos a utilizar no cálculo do tempo de tráfego. Esta configuração afeta o valor retornado no campo duration_in_traffic na resposta, que contém o tempo previsto no tráfego com base em médias históricas. traffic_model parâmetro pode ser especificado somente para pedidos em que o modo de viagem é driving, e quando o pedido inclui um departure_time, e somente se a solicitação inclui uma chave de API ou um Google Maps Platform Plano Premium ID de cliente. Os valores disponíveis para este parâmetro são::
    • best_guess (default) indica que o retornado duration_in_traffic deve ser a melhor estimativa do tempo de viagem dado o que é conhecido tanto sobre as condições históricas de tráfego e tráfego ao vivo. O tráfego ao vivo torna-se mais importante quanto mais próximo estiver o departure_time.
    • pessimisticindica que o retornoduration_in_traffic deve ser maior do que o tempo real de viagem na maioria dos dias, embora dias ocasionais com condições de tráfego particularmente más podem exceder este valor.
    • optimistic indica que o retornado duration_in_traffic deve ser mais curto do que o tempo de viagem real, na maioria dos dias, apesar de ocasionais dias especialmente com boas condições de tráfego pode ser mais rápido do que este valor.
  • transit_mode — especifica um ou mais modos preferidos de trânsito. Este parâmetro só pode ser especificado para pedidos em que o modetransit. O parâmetro suporta os seguintes argumentos:
    • bus indica que a rota calculada deve preferir viajar de autocarro.
    • subway indica que a rota calculada deve preferir viajar de metro.
    • train indica que o itinerário calculado deve preferir viajar de comboio.
    • tram indica que o itinerário calculado deve preferir viajar de eléctrico e de comboio ligeiro.
    • rail indica que o itinerário calculado deve preferir viajar de comboio, eléctrico, comboio ligeiro e metro. Isto é equivalente a .
  • transit_routing_preference — especifica preferências para pedidos de trânsito. Usando este parâmetro, você pode distorcer as opções retornadas, ao invés de aceitar a melhor rota padrão escolhida pela API. Este parâmetro só pode ser especificado para pedidos em que o modetransit. O parâmetro suporta os seguintes argumentos:
    • less_walking indica que a rota calculada deve preferir quantidades limitadas de caminhada.
    • fewer_transfers indica que a rota calculada deve preferir um número limitado de transferências.

  modos de viagem

  para o cálculo das distâncias, pode especificar o transportemode a utilizar. Por padrão, as distâncias são calculadas para o modo de condução. São suportados os seguintes modos de viagem:

  • driving (por omissão) indica o cálculo da distância através da rede rodoviária.
  • walking solicita o cálculo da distância para percorrer caminhos pedonais& calçadas (quando disponível).
  • bicycling solicita o cálculo da distância para Bicicletas através de ciclovias& ruas preferidas (quando disponível).
  • transit solicita o cálculo da distância através de rotas de trânsito público (quando disponível). Este valor só pode ser especificado se o pedido incluir uma chave API ou um ID do cliente do Plano Premium da plataforma do Google Maps. Se definir o modo para transit pode indicar opcionalmente um departure_time ou um arrival_time. Se nenhuma das Horas for especificada, o departure_time corresponde agora (isto é, a hora de partida corresponde à hora actual). Você também pode opcionalmente incluir um transit_mode e/ou um transit_routing_preference.

  de informações de Trânsito

  o Tráfego de informações é usado quando todas as seguintes aplicam-se (estas são as condições necessárias para receber o duration_in_traffic campo na Matriz de Distância resposta):

  • A viagem mode parâmetro driving ou não é especificado (driving é o padrão de modo de viagem).
  • o pedido inclui um parâmetro válido departure_time. O departure_time pode ser definido para o tempo atual ou algum tempo no futuro. Não pode ser no passado.

  Opcionalmente, você pode incluir o parâmetro traffic_model no seu pedido para especificar os pressupostos a usar ao calcular o tempo no tráfego.

  a seguinte URL inicia um pedido de matriz de distância para a condução de distâncias entre Boston, MA ou Charlestown, MA, e Lexington, MA e Concord, MA. O pedido inclui uma hora de partida, cumprindo todos os requisitos para retornar o campo duration_in_traffic na Resposta da matriz de distância.

  restrições

  distâncias podem ser calculadas que aderem 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 evitar. As restrições a seguir são suportados:

  • avoid=tolls
  • avoid=highways
  • avoid=ferries
  • avoid=indoor

  * Nota: a adição de restrições não impede rotas que incluem a funcionalidade restrita; ele os preconceitos de que o resultado mais favorável rotas.

  a Unidade de sistemas

  da Matriz de Distância de resultados conter text dentro de distance campos para indicar a distância da rota calculada. O sistema unitário a usar pode ser especificado:

  • units=metric (por omissão) devolve distâncias em quilómetros e metros.
  • units=imperial devolve distâncias em milhas e pés.

  * Nota: Esta configuração do sistema de unidades afecta apenas os campos text exibidos dentro de distance. Os camposdistance também contêm que são sempre expressos em metros.

  as respostas da matriz de distância

  as respostas às perguntas de API da matriz de distância são devolvidas no formato indicado pelooutput