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_timee umtraffic_modelopcional.
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
- Serviço a ser ativado:
distance-matrix-backend.googleapis.com - Autenticação: chave de API
- Comece agora: configure a API Distance Matrix
- Referência: referência da API Distance Matrix
- Preços: uso e faturamento da API Distance Matrix
- Políticas: políticas da API Distance Matrix
- Notas da versão: notas da versão da API Distance Matrix
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_EXCEEDEDouMAX_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 nenhumduration_in_trafficserá retornado. Os resultados podem variar ao longo do tempo. Correção: definadeparture_timecomonowou um horário futuro commode=drivingpara 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
unitsmuda apenas o texto nos campos de distância. O valor da distância é sempre em metros. Correção: leiadistance.valuecomo metros ou usedistance.textpara 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_DENIEDemstatuse umerror_messagecom link paraLegacyApiNotActivatedMapError. Os assistentes de IA geralmente geram código de API legado por padrão. Correção: migre para a API RoutescomputeRouteMatrix(com o cabeçalhoX-Goog-FieldMask). Ative a API legada por formulário apenas como uma medida de curto prazo. Consulte /maps/legacy#LegacyApiNotActivatedMapError.