Rotas

Aplicações

O endpoint de Rotas calcula o caminho ótimo entre dois ou mais pontos geográficos, retornando a geometria da rota em WKT (LINESTRING) além de métricas de distância, tempo, subida e descida acumuladas. É a base para operações que dependem de deslocamento real na malha viária — não apenas distância euclidiana.

Conceito

A API de Rotas calcula o caminho ótimo entre pontos sobre a malha viária brasileira. Diferente da distância em linha reta (haversine), o algoritmo respeita ruas, sentidos, restrições de acesso e características viárias — retornando o trajeto que efetivamente pode ser percorrido.

A entrada aceita dois ou mais pontos no formato lat,lng. Quando são fornecidos múltiplos waypoints, o cálculo segue a ordem informada (o primeiro ponto é a origem, o último é o destino, os intermediários são paradas obrigatórias). O perfil (car, foot, bike) determina a rede considerada e a velocidade média — alterando o caminho ótimo e o tempo estimado.

Convenção de Sinais

Quando a rota é calculada com sucesso, o retorno traz a geometria em WKT e as métricas preenchidas. Quando não existe caminho possível entre os pontos (por exemplo, pontos em ilhas isoladas sem ligação viária ou perfis incompatíveis com a malha), o comportamento por endpoint difere:

Parâmetros de Entrada

Batch: POST /routing/batch/route — corpo JSON com items (máx. 16; cada item traz points: [[lat, lng], ...]) + profile, sentido e piso_geodesico_m aplicados a todo o lote.

Matriz 1→N (Fase 2): POST /routing/route/matrix — uma origem e até 1.024 destinos (cada um com id opcional ecoado na resposta). Cada item traz todos os campos derivados da rota. Cache interno por par (origem, destino, profile, sentido, versão da malha) com TTL de 12 h. Sentido ambos não é suportado no matrix (dobraria a cardinalidade).

Exemplos

Dois cenários ilustram os padrões de resposta da API — uma rota simples entre dois pontos e uma rota com waypoints intermediários.

Rota simples (origem → destino) -19.9191,-43.9378 → -19.9498,-43.9477

GET /routing/route?points=-19.9191,-43.9378&points=-19.9498,-43.9477&profile=car

{
  "geometria": "LINESTRING (-43.9378 -19.9191, -43.94 -19.93, -43.9477 -19.9498)",
  "distancia_m": 1500.5,
  "tempo_s": 180.0,
  "subida_m": 50.0,
  "descida_m": 30.0,
  "distancia_geodesica_m": 1123.4,
  "indice_de_desvio": 1.336,
  "indice_de_desvio_confiavel": true,
  "piso_geodesico_m": 500,
  "velocidade_media_rota_kmh": 30.01,
  "velocidade_media_geodesica_kmh": 22.47,
  "snap_origem_m": 12.4,
  "snap_destino_m": 8.7,
  "sentido": "origem_destino",
  "status": "OK",
  "versao_malha_viaria": "20260322-9110d1b2",
  "data_calculo": "2026-09-01T14:32:11+00:00",
  "origem_cache": false
}

A rota tem 1.500 m de extensão viária real contra 1.123 m em linha reta — indice_de_desvio ≈ 1,34 (o carro roda 34% a mais do que a haversine, típico de malha urbana). Tempo estimado 3 min a 30 km/h médios (proxy de hierarquia viária, não de tráfego). indice_de_desvio_confiavel=true porque a geodésica (1.123 m) supera o piso_geodesico_m=500. A geometria em WKT pode ser plotada diretamente em PostGIS, QGIS ou Leaflet via wellknown.

POST /routing/batch/route

{
  "items": [
    { "points": [[-23.55, -46.63], [-23.56, -46.64], [-23.57, -46.65]] },
    { "points": [[-22.90, -43.17], [-22.91, -43.18]] }
  ],
  "profile": "car"
}

// Resposta
{
  "TOTAL": 2,
  "SUCESSOS": 2,
  "FALHAS": 0,
  "RESULTADOS": [
    {
      "sucesso": true,
      "dados": {
        "geometria": "LINESTRING (-46.63 -23.55, -46.64 -23.56, -46.65 -23.57)",
        "distancia_m": 3120.4,
        "tempo_s": 420.0,
        "subida_m": 12.0,
        "descida_m": 18.0
      },
      "erro": null
    },
    {
      "sucesso": true,
      "dados": { "geometria": "LINESTRING (...)", "distancia_m": 1590.2, "tempo_s": 210.0, "subida_m": 5.0, "descida_m": 7.0 },
      "erro": null
    }
  ]
}

Atributos Retornados

A resposta é composta pela geometria da rota em WKT e pelas métricas acumuladas ao longo do trajeto. Nos exemplos abaixo os campos são apresentados sem o prefixo prismadata__routing_route__ presente no schema oficial.

Detalhes Técnicos

Limitações