# Rotas

> Calculo de rotas entre pontos (simples e batch)

**Base**: `https://api.prismadata.io/v1`

**Autenticação**: header `X-Apikey` (ou query `api_key`). Detalhes em [Autenticação](autenticacao.md).

**Formato de resposta**: JSON plano com campos `prismadata__<serviço>__<campo>`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md).

## Endpoints

### `GET /routing/route`

Calcula rota entre pontos com campos derivados (Fase 1).

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/routing/route?points=[-19.9323, -43.9351]" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: profile=car, piso_geodesico_m=500, sentido=ida
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `points` | query | array[string] | sim | Pontos no formato 'lat,lon' (minimo 2) |
| `profile` | query | string | não | Perfil de roteamento |
| `piso_geodesico_m` | query | integer | não | Piso de validade do INDICE_DE_DESVIO. Nao afeta o calculo, so decide INDICE_DE_DESVIO_CONFIAVEL e o STATUS. Default 500m. |
| `sentido` | query | string | não | ida (default): origem->destino. volta: destino->origem. ambos: retorna os dois sentidos como lista. |

**Response 200** (`application/json`):

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__routing_route__geometria` | string \| null | sim | Geometria em WKT (LINESTRING). Null quando STATUS=SEM_ROTA. |
| `prismadata__routing_route__distancia_m` | number \| null | sim | Distancia total pela malha em metros. Null se SEM_ROTA. |
| `prismadata__routing_route__subida_m` | number \| null | sim | Subida total em metros. |
| `prismadata__routing_route__descida_m` | number \| null | sim | Descida total em metros. |
| `prismadata__routing_route__tempo_s` | number \| null | sim | Tempo estimado em segundos. Sem tráfego em tempo real. |
| `prismadata__routing_route__distancia_geodesica_m` | number | sim | Haversine entre coordenadas cruas (linha reta, WGS84). |
| `prismadata__routing_route__indice_de_desvio` | number \| null | sim | distancia_m / distancia_geodesica_m. Sem clamp. Valores <1 indicam ruído de snap dominante. Null se SEM_ROTA. |
| `prismadata__routing_route__indice_de_desvio_confiavel` | boolean | sim | True se distancia_geodesica_m >= piso_geodesico_m. |
| `prismadata__routing_route__piso_geodesico_m` | integer | sim | Piso efetivo usado (eco do parametro do request, default 500). |
| `prismadata__routing_route__velocidade_media_rota_kmh` | number \| null | sim | distancia_m/tempo_s. Proxy de hierarquia viária, NAO de tráfego. |
| `prismadata__routing_route__velocidade_media_geodesica_kmh` | number \| null | sim | distancia_geodesica_m/tempo_s. Útil pra comparar redes. |
| `prismadata__routing_route__snap_origem_m` | number \| null | sim | Distância entre coord crua de origem e sua projeção na malha. |
| `prismadata__routing_route__snap_destino_m` | number \| null | sim | Idem para o destino. |
| `prismadata__routing_route__sentido` | string | sim | origem_destino \| destino_origem. |
| `prismadata__routing_route__status` | string | sim | OK \| SEM_ROTA \| ABAIXO_DO_PISO. |
| `prismadata__routing_route__versao_malha_viaria` | string | sim | Versão do grafo (formato AAAAMMDD-<sha8>). |
| `prismadata__routing_route__data_calculo` | string | sim | Timestamp UTC ISO 8601 do cálculo. |
| `prismadata__routing_route__origem_cache` | boolean | sim | True se o item veio do cache interno. |

**Outros códigos**: 403, 422, 429

---

### `POST /routing/batch/route`

Calcula multiplas rotas em batch.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/routing/batch/route" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "items": [
           {
             "points": [
               -19.9323,
               -43.9351
             ]
           }
         ],
         "profile": "car",
         "piso_geodesico_m": 500,
         "sentido": "ida"
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `items` | array[object] | sim | Lista de rotas a calcular |
| `profile` | string | não | Perfil de roteamento |
| `piso_geodesico_m` | integer | não |  |
| `sentido` | string | não |  |

**Response 200** (`application/json`):

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `TOTAL` | integer | sim | Total de rotas solicitadas |
| `SUCESSOS` | integer | sim | Quantidade de rotas calculadas com sucesso |
| `FALHAS` | integer | sim | Quantidade de rotas que falharam |
| `RESULTADOS` | array[object] | sim | Lista de resultados |

**Outros códigos**: 403, 422, 429

---

### `POST /routing/route/matrix`

Matriz 1->N publica (Fase 2): uma origem, ate 1024 destinos. Todos os campos derivados da Fase 1 vem por item. Cache por par (origem, destino, profile, sentido, versao_malha) com TTL 12h.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/routing/route/matrix" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "origem": {
           "lat": -19.9323,
           "lng": -43.9351
         },
         "destinos": [
           {
             "id": "string",
             "lat": -19.9323,
             "lng": -43.9351
           }
         ],
         "profile": "car",
         "piso_geodesico_m": 500,
         "sentido": "ida"
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `origem` | object | sim | Ponto de origem unico da matriz 1->N. |
| `destinos` | array[object] | sim |  |
| `profile` | string | não |  |
| `piso_geodesico_m` | integer | não |  |
| `sentido` | string | não | ambos nao suportado na matriz (dobraria a cardinalidade) |

**Response 200** (`application/json`):

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `rotas` | array[object] | sim | Um item por destino, na mesma ordem do request. |

**Outros códigos**: 403, 422, 429

---

## Recursos relacionados

- Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/Rotas
- OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/rotas.json
- OpenAPI completo: https://prismadata.io/openapi.yaml
- Índice geral: https://prismadata.io/llms.txt