Referência rápida da API Distance Matrix

A API Distance Matrix (legada) é um serviço da Web que retorna a distância e o tempo de viagem para uma matriz de origens e destinos, com base na rota recomendada entre cada par. É possível definir o modo de viagem (carro, a pé, bicicleta, transporte público), os meios de transporte público, as unidades e o horário de partida para durações com base no trânsito. Ele retorna JSON ou XML.

API Distance Matrix: fatos importantes

  • Produto: API Distance Matrix
  • Também conhecida como: API Distance Matrix (legada), Distance Matrix (legada)
  • Categoria: rotas
  • Plataforma: serviço da Web (REST)
  • Executado em: servidor (código de back-end)
  • Estágio de lançamento: GA
  • Ciclo de vida: legado
  • Substituída por: API Routes
  • Visão geral: visão geral da API Distance Matrix

API Distance Matrix: quando usar

Use a API Distance Matrix quando:

  • Você mantém um projeto que já tem a API Distance Matrix (legada) ativada e chama /maps/api/distancematrix.
  • Você precisa da distância e do tempo de viagem entre várias origens e vários destinos de um servidor.
  • Você precisa de durações no trânsito para dirigir, usando departure_time e um traffic_model opcional.

Não use a API Distance Matrix quando:

  • Você está iniciando um novo projeto do Google Cloud. A partir de outubro de 2026, a API Distance Matrix (legada) não poderá ser ativada para novos projetos. Use a API Routes.
  • Você precisa de novos recursos ou de uma matriz de rotas de até 625 elementos com respostas transmitidas (computeRouteMatrix). Use a API Routes.
  • Você precisa de um trajeto completo com etapas e polilinhas entre os pontos, não apenas valores de distância e duração. Use a API Routes.

API Distance Matrix: configuração

API Distance Matrix: erros comuns

  • Problema: cada solicitação do lado do servidor é limitada a 100 elementos (origens × destinos) e a 25 origens ou 25 destinos. Solicitações maiores retornam MAX_ELEMENTS_EXCEEDED ou MAX_DIMENSIONS_EXCEEDED. Correção: divida a matriz em solicitações de no máximo 100 elementos e 25 origens ou destinos. Consulte /maps/documentation/distance-matrix/usage-and-billing#usage-limits.
  • Problema: se você não especificar departure_time, o trajeto e a duração serão baseados no trânsito médio independente do horário, e nenhum duration_in_traffic será retornado. Os resultados podem variar ao longo do tempo. Correção: defina departure_time como now ou um horário futuro com mode=driving para receber durações que consideram o trânsito. As solicitações de trânsito têm uma taxa mais alta. Consulte /maps/documentation/distance-matrix/distance-matrix.
  • Problema: o parâmetro units muda apenas o texto nos campos de distância. O valor da distância é sempre em metros. Correção: leia distance.value como metros ou use distance.text para exibição. Consulte /maps/documentation/distance-matrix/distance-matrix.
  • Problema: chamar a API Distance Matrix (legada) em um projeto em que ela não está ativada retorna REQUEST_DENIED em status e um error_message com link para LegacyApiNotActivatedMapError. Os assistentes de IA geralmente geram código de API legado por padrão. Correção: migre para a API Routes computeRouteMatrix (com o cabeçalho X-Goog-FieldMask). Ative a API legada por formulário apenas como uma medida de curto prazo. Consulte /maps/legacy#LegacyApiNotActivatedMapError.