Skip to main content

​
Visão geral

Calcula distâncias e tempos de viagem entre múltiplos pontos de origem e destino. É útil para otimização de rotas e cálculo de custos de frete.

​
Endpoint

GET /api/maps/distance-matrix

​
Parâmetros de Query

ParâmetroTipoObrigatórioDescrição
originsstringSimCoordenadas de origem no formato lat,lng ou múltiplas separadas por ``
destinationsstringSimCoordenadas de destino no formato lat,lng ou múltiplas separadas por ``

​
Formato de Coordenadas

  • Ponto único: -23.5505,-46.6333
  • Múltiplos pontos: -23.5505,-46.6333|-22.9068,-43.1729

​
Exemplo de Requisição

# Origem única para destino único
curl -H "X-API-Key: sua_chave_aqui" \
  "https://api.fretamaps.com.br/api/distance-matrix?origins=-23.5505,-46.6333&destinations=-22.9068,-43.1729"

# Múltiplas origens e destinos
curl -H "X-API-Key: sua_chave_aqui" \
  "https://api.fretamaps.com.br/api/distance-matrix?origins=-23.5505,-46.6333|-23.5632,-46.6544&destinations=-22.9068,-43.1729|-23.5678,-46.6789"

​
Exemplo de Resposta

{
  "origin_addresses": [
    "São Paulo, SP, Brasil"
  ],
  "destination_addresses": [
    "Rio de Janeiro, RJ, Brasil"
  ],
  "rows": [
    {
      "elements": [
        {
          "status": "OK",
          "duration": {
            "text": "6 horas 12 minutos",
            "value": 22320
          },
          "distance": {
            "text": "429 km",
            "value": 429000
          }
        }
      ]
    }
  ],
  "status": "OK",
  "source": "Google"
}

​
Estrutura de Resposta

​
origin_addresses
array
required
Array de endereços formatados das origens
​
destination_addresses
array
required
Array de endereços formatados dos destinos
​
rows
array
required
Array de linhas da matriz (uma por origem)
​
rows[].elements
array
required
Array de elementos (um por destino)
​
rows[].elements[].status
string
required
Status do cálculo: "OK" ou código de erro
​
rows[].elements[].duration
object
required
Duração da viagem
​
rows[].elements[].duration.text
string
required
Duração formatada (ex: “6 horas 12 minutos”)
​
rows[].elements[].duration.value
integer
required
Duração em segundos
​
rows[].elements[].distance
object
required
Distância da viagem
​
rows[].elements[].distance.text
string
required
Distância formatada (ex: “429 km”)
​
rows[].elements[].distance.value
integer
required
Distância em metros
​
status
string
required
Status geral da resposta: "OK" ou código de erro
​
source
string
required
Fonte dos dados: "Google", "Here" ou "Cache"
​
error_message
string
Mensagem de erro (apenas se status for erro)

​
Headers de Resposta

  • X-Cache: HIT se veio do cache, MISS se foi buscado da API
  • X-Provider: Google ou Here
  • X-Format: Standard

​
Códigos de Status

  • 200 OK - Requisição bem-sucedida
  • 400 Bad Request - Parâmetros origins ou destinations não fornecidos
  • 401 Unauthorized - Autenticação falhou
  • 500 Internal Server Error - Erro ao buscar dados do provedor

​
Notas

  • Distâncias: Sempre retornadas em metros no campo value
  • Durações: Sempre retornadas em segundos no campo value
  • O modo de transporte é sempre driving (veículo particular)
  • Para matrizes grandes, considere usar o cache para reduzir custos
  • O sistema suporta até 25 origens e 25 destinos por requisição (limites do provedor)

​
Exemplo com Múltiplos Pontos

{
  "origin_addresses": [
    "São Paulo, SP, Brasil",
    "Campinas, SP, Brasil"
  ],
  "destination_addresses": [
    "Rio de Janeiro, RJ, Brasil",
    "Belo Horizonte, MG, Brasil"
  ],
  "rows": [
    {
      "elements": [
        {
          "status": "OK",
          "duration": {"text": "6 horas", "value": 21600},
          "distance": {"text": "429 km", "value": 429000}
        },
        {
          "status": "OK",
          "duration": {"text": "7 horas", "value": 25200},
          "distance": {"text": "586 km", "value": 586000}
        }
      ]
    },
    {
      "elements": [
        {
          "status": "OK",
          "duration": {"text": "5 horas", "value": 18000},
          "distance": {"text": "358 km", "value": 358000}
        },
        {
          "status": "OK",
          "duration": {"text": "6 horas", "value": 21600},
          "distance": {"text": "515 km", "value": 515000}
        }
      ]
    }
  ],
  "status": "OK",
  "source": "Google"
}