Skip to main content

​
Visão geral

Calcula rotas completas entre um ponto de origem e um destino, com suporte a waypoints (pontos intermediários). Retorna distâncias e durações totais, além de informações sobre cada segmento da rota.

​
Endpoint

POST /api/maps/directions

​
Método

POST (requer body JSON)

​
Body da Requisição

{
  "origin": "-23.5505,-46.6333",
  "destination": "-22.9068,-43.1729",
  "waypoints": ["-23.5632,-46.6544"],
  "force_refresh": false
}

​
Parâmetros do Body

ParâmetroTipoObrigatórioDescrição
originstringSimCoordenadas de origem no formato lat,lng
destinationstringSimCoordenadas de destino no formato lat,lng
waypointsarrayNãoArray de coordenadas intermediárias no formato ["lat,lng", ...]
force_refreshbooleanNãoSe true, força busca na API ignorando cache (padrão: false)
providerstringNãoForça uso de um provedor específico: "google" ou "here"

​
Exemplo de Requisição

# Rota simples (sem waypoints)
curl -X POST \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "-23.5505,-46.6333",
    "destination": "-22.9068,-43.1729"
  }' \
  https://api.fretamaps.com.br/api/directions

# Rota com waypoints
curl -X POST \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "-23.5505,-46.6333",
    "destination": "-22.9068,-43.1729",
    "waypoints": [
      "-23.5632,-46.6544",
      "-23.5678,-46.6789"
    ]
  }' \
  https://api.fretamaps.com.br/api/directions

​
Exemplo de Resposta

{
  "status": "OK",
  "total_distance": 429000,
  "total_duration": 22320,
  "base_duration": 21600,
  "pairs_distances": {
    "-23.5505,-46.6333;-22.9068,-43.1729": {
      "distance": 429000,
      "duration": 22320,
      "pair": "-23.5505,-46.6333;-22.9068,-43.1729"
    }
  },
  "source": "Google",
  "origin": {
    "lat": -23.5505,
    "lng": -46.6333
  },
  "destination": {
    "lat": -22.9068,
    "lng": -43.1729
  },
  "stop_points": []
}

​
Estrutura de Resposta

​
status
string
required
Status da resposta: "OK" ou código de erro
​
total_distance
integer
required
Distância total da rota em metros
​
total_duration
integer
required
Duração total da rota em segundos (considera tráfego atual)
​
base_duration
integer
Duração base sem tráfego em segundos (principalmente para HERE)
​
pairs_distances
object
required
Mapa de distâncias por par de pontos (chave: “lat1,lng1;lat2,lng2”)
​
pairs_distances[].distance
integer
required
Distância do segmento em metros
​
pairs_distances[].duration
integer
required
Duração do segmento em segundos
​
pairs_distances[].pair
string
required
Chave do par no formato “lat1,lng1;lat2,lng2”
​
pairs_distances[].hereCoords
string
Coordenadas HERE específicas (apenas para provedor HERE)
​
source
string
required
Fonte dos dados: "Google", "Here" ou "Cache"
​
origin
object
required
Coordenadas de origem
​
origin.lat
number
required
Latitude da origem
​
origin.lng
number
required
Longitude da origem
​
destination
object
required
Coordenadas de destino
​
destination.lat
number
required
Latitude do destino
​
destination.lng
number
required
Longitude do destino
​
stop_points
array
Array de coordenadas dos waypoints
​
stop_points[].lat
number
Latitude do waypoint
​
stop_points[].lng
number
Longitude do waypoint

​
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 origin ou destination não fornecidos ou inválidos
  • 401 Unauthorized - Autenticação falhou
  • 500 Internal Server Error - Erro ao buscar dados do provedor

​
Exemplo com Waypoints

{
  "status": "OK",
  "total_distance": 123456,
  "total_duration": 7200,
  "pairs_distances": {
    "-23.5505,-46.6333;-23.5632,-46.6544": {
      "distance": 12345,
      "duration": 1800,
      "pair": "-23.5505,-46.6333;-23.5632,-46.6544"
    },
    "-23.5632,-46.6544;-23.5678,-46.6789": {
      "distance": 23456,
      "duration": 3600,
      "pair": "-23.5632,-46.6544;-23.5678,-46.6789"
    },
    "-23.5678,-46.6789;-22.9068,-43.1729": {
      "distance": 87655,
      "duration": 1800,
      "pair": "-23.5678,-46.6789;-22.9068,-43.1729"
    }
  },
  "source": "Google",
  "origin": {
    "lat": -23.5505,
    "lng": -46.6333
  },
  "destination": {
    "lat": -22.9068,
    "lng": -43.1729
  },
  "stop_points": [
    {
      "lat": -23.5632,
      "lng": -46.6544
    },
    {
      "lat": -23.5678,
      "lng": -46.6789
    }
  ]
}

​
Notas

  • Distâncias: Sempre retornadas em metros
  • Durações: Sempre retornadas em segundos
  • O modo de transporte é sempre driving (veículo particular)
  • O sistema considera tráfego atual ao calcular durações
  • Rotas são armazenadas em cache para reduzir custos
  • Use force_refresh: true para forçar recálculo ignorando cache
  • O sistema suporta até 25 waypoints por rota (limite do provedor)
  • Em caso de falha na API de Directions, o sistema faz fallback automático para Distance Matrix