API › Routing › Rotas

# Rotas

Roteamento ponto a ponto entre coordenadas com distância, tempo, subida, descida e geometria (WKT) — para last-mile, logística, catchment area e planejamento de território. 

Categoria Routing

Cobertura Nacional

Perfis car · foot · bike

Batch até 16 rotas

Nesta página

Aplicações Conceito Convenção de sinais Entradas Exemplos Atributos retornados Detalhes técnicos Limitações

Para que serve

## 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. 

#### Last-mile & Logística

Estime tempo e distância reais de entrega entre CD e destino final, incluindo pontos intermediários da rota de distribuição.

#### Catchment Area

Calcule a rota real (não linha reta) entre clientes e pontos de atendimento para dimensionar a área de captação de uma loja ou agência.

#### Território de Vendas

Defina territórios de representantes comerciais baseados em tempo de deslocamento entre contas, otimizando roteiros de visita.

#### Análise de Cobertura

Verifique a distância real percorrível entre pontos de rede (agências, filiais, postos) para identificar sobreposição e gaps.

Entendendo o dado

## 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. 

Interpretação

## 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: 

●

**Rota encontrada** Todos os campos obrigatórios (geometria, distancia_m, tempo_s, subida_m, descida_m) retornam preenchidos e o HTTP status é 200.

○

**Rota impossível — endpoint /route** O endpoint retorna HTTP 422 (Validation Error) quando não existe caminho viável entre os pontos ou os parâmetros são inválidos.

○

**Rota impossível — endpoint /batch/route** O item traz `sucesso: false`, `dados: null` e uma mensagem em `erro`, sem interromper o processamento dos demais itens do lote.

Request

## Parâmetros de Entrada

`points` array<string>

Lista de pontos no formato `lat,lng`, informados como parâmetros repetidos na query string. Mínimo de 2 pontos (origem e destino); waypoints intermediários são respeitados na ordem informada.

`profile` enum

Perfil de roteamento. Valores: `car`, `foot`, `bike`. Default: `car`.

`sentido` enum

Direção do cálculo: `ida` (origem→destino, default), `volta` (destino→origem) ou `ambos` (retorna os dois sentidos como lista, dobra a cardinalidade da resposta).

`piso_geodesico_m` integer · metros

Piso de validade do `indice_de_desvio`. Não afeta o cálculo da rota; só decide se o índice sai como confiável e qual o `status`. Faixa 0–5000, default `500`.

**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). 

Na prática

## 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

![Mapa: rota traçada entre dois pontos em Belo Horizonte, começando no ponto 1 \(Estação Ferroviária\) e terminando no ponto 2 \(Sion\)](https://prismadata.io/imagens/rotas/exemplo_1.jpeg)
    
    
    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. 

Rota multi-waypoints (batch) 2 rotas · 3 waypoints cada
    
    
    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
        }
      ]
    }

No batch, a primeira rota tem três waypoints — origem, parada intermediária e destino — todos respeitados na ordem informada. O envelope traz contadores agregados (`TOTAL`, `SUCESSOS`, `FALHAS`) e cada item carrega o próprio flag `sucesso`. 

Response

## 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. 

Geometria

geometria

Geometria da rota em formato WKT (LINESTRING) com coordenadas `lng lat` (padrão WKT). Pode ser convertida para GeoJSON com bibliotecas como `shapely`, `wellknown` ou funções PostGIS `ST_GeomFromText`.

Métricas de trajeto

distancia_m

Distância total do trajeto pela malha viária, em metros (não linha reta). `null` se `status=SEM_ROTA`.

tempo_s

Tempo estimado de percurso, em segundos, considerando o perfil e velocidades da malha. Sem tráfego em tempo real.

subida_m

Elevação acumulada positiva ao longo do trajeto, em metros (soma dos aclives).

descida_m

Elevação acumulada negativa ao longo do trajeto, em metros (soma dos declives).

distancia_geodesica_m

Distância haversine (linha reta, WGS84) entre origem e destino cruas. Referência geométrica pura, ignora a malha.

Qualidade e desvio (Fase 1)

indice_de_desvio

`distancia_m / distancia_geodesica_m`. Mede o quanto a malha viária desvia da linha reta. Sem clamp; valores `<1` indicam ruído dominante do snap às vias (par muito próximo). `null` se `status=SEM_ROTA`.

indice_de_desvio_confiavel

Booleano: `true` quando `distancia_geodesica_m ≥ piso_geodesico_m`. Use para filtrar pares muito próximos onde o índice é dominado por snap.

piso_geodesico_m

Piso efetivo usado (eco do parâmetro do request, default 500 m).

velocidade_media_rota_kmh

`distancia_m / tempo_s` em km/h. Proxy de hierarquia viária (arterial × local), **não** de tráfego real.

velocidade_media_geodesica_kmh

`distancia_geodesica_m / tempo_s`. Útil para comparar redes ou eficiência espacial entre rotas.

snap_origem_m

Distância entre a coordenada crua de origem e sua projeção na malha viária. Valores altos indicam origem longe de vias mapeadas.

snap_destino_m

Análogo para o destino.

Metadados da rota

sentido

Sentido efetivamente calculado: `origem_destino` ou `destino_origem`. Em `sentido=ambos`, o response traz uma lista com um item por sentido.

status

Status do cálculo: `OK` (rota válida), `SEM_ROTA` (sem caminho viário entre pontos), `ABAIXO_DO_PISO` (rota calculada mas geodésica menor que o piso — `indice_de_desvio_confiavel=false`).

versao_malha_viaria

Versão do grafo utilizado no cálculo, formato `AAAAMMDD-<sha8>`. Útil para reprodução: rotas com a mesma versão da malha e mesmos parâmetros retornam resultado idêntico.

data_calculo

Timestamp UTC ISO 8601 do momento em que o cálculo foi feito (ou recuperado do cache).

origem_cache

Booleano: `true` quando o item veio do cache interno (ex.: matrix TTL 12 h), `false` quando foi recalculado.

Envelope batch (`/batch/route`)

TOTAL

Quantidade total de rotas solicitadas no lote.

SUCESSOS

Rotas calculadas com sucesso.

FALHAS

Rotas que falharam.

RESULTADOS[].sucesso

Booleano por item.

RESULTADOS[].dados

Objeto com todos os campos de rota (métricas + qualidade + metadados) quando `sucesso=true`. `null` em falha.

RESULTADOS[].erro

Mensagem descritiva do erro quando `sucesso=false`.

Envelope matriz 1→N (`/route/matrix`)

rotas[]

Lista com um item por destino, na mesma ordem do request. Cada item traz o `id` eco (se fornecido no destino) e todos os campos de rota (mesmo shape do endpoint single).

Referência

## Detalhes Técnicos

#### Fontes

  * Malha viária brasileira derivada de fontes públicas abertas
  * Motor de roteamento próprio da PrismaData
  * Modelo digital de elevação (para cálculo de subida/descida)

#### Metodologia

Busca do menor tempo entre pontos sobre o grafo viário, respeitando sentidos, restrições e o perfil solicitado (car, foot ou bike).

#### Frequência de Atualização

Malha viária atualizada periodicamente a partir de snapshots públicos.

#### Cobertura

Todo o território nacional coberto pela malha viária pública. Trechos sem representação no grafo não são roteáveis.

Atenção

## Limitações

####  Considere ao utilizar 

  * O cálculo não considera **tráfego em tempo real** : o tempo estimado (`tempo_s`) é baseado em velocidades médias por tipo de via, sem ajuste para congestionamento, horário de pico ou eventos. Para catchment com trânsito use as isócronas com `condicao_transito`.
  * O endpoint em lote `/routing/batch/route` tem limite máximo de **16 rotas por requisição**. Para volumes maiores, use `/routing/route/matrix` (até 1.024 destinos por chamada) ou particione o processamento no lado cliente.
  * A matriz `/route/matrix` **não suporta** `sentido=ambos` (dobraria a cardinalidade — chame o endpoint duas vezes se precisar).
  * Pontos localizados fora da malha viária pública (áreas isoladas, ilhas sem ligação rodoviária) podem não ter rota viável — o endpoint retorna `status=SEM_ROTA` com `geometria` e `distancia_m` nulos; no batch, o item traz `sucesso=false`.
  * Em pares muito próximos, `indice_de_desvio` pode ficar dominado por ruído de snap às vias (valores `<1`). Use o flag `indice_de_desvio_confiavel` ou ajuste `piso_geodesico_m` conforme a granularidade do caso.
  * A qualidade de `subida_m` e `descida_m` depende da disponibilidade e resolução do modelo digital de elevação na região consultada.
  * Waypoints intermediários são respeitados na **ordem informada**. A API não faz otimização de sequência (TSP) — se precisar do menor tempo total visitando N pontos em qualquer ordem, resolva o TSP antes de chamar o endpoint.

## Pronto para testar?

Experimente a API de Rotas no playground interativo com seus próprios pontos e perfis.

[ Abrir playground  ](<../api-playground/rotas-isocronas/>)