# Isocronas

> Calculo de areas de alcance (isocronas 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/isochrone`

Calcula isocrona (por tempo) ou isodistancia (por distancia) a partir de um ponto.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/routing/isochrone?lat=-19.9323&lng=-43.9351" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: time_limit=0, distance_limit=0, profile=car, sentido=SAINDO, condicao_transito=normal
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude do ponto central |
| `lng` | query | number | sim | Longitude do ponto central |
| `time_limit` | query | integer \| null | não | Limite de TEMPO em segundos (60..7200). Mutuamente exclusivo com `distance_limit`. Se nenhum for informado, aplica default de 600s. |
| `distance_limit` | query | integer \| null | não | Limite de DISTANCIA em metros (100..50000). Ativa modo isodistancia — corta o Dijkstra na distancia acumulada da malha viaria (nao euclidiana). Mutuamente exclusivo com `time_limit`. |
| `profile` | query | string | não | Perfil de roteamento |
| `sentido` | query | string | não | SAINDO (do ponto) ou INDO (para o ponto) |
| `condicao_transito` | query | string | não | Nivel de trânsito. Aplica multiplicador ao time_limit antes do motor de roteamento: livre=1.0, normal=0.7 (default), pico_moderado=0.5, pico_pesado=0.3. Só efetivo no modo tempo; ignorado no modo distância. Bloco `CONDICAO_TRANSITO/FATOR_TEMPORAL/LIMITE_TEMPO_S_EFETIVO/MUNICIPIO_IBGE` no output documenta o ajuste aplicado. |

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

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__routing_isochrone__geometria` | string | sim | Geometria em WKT (POLYGON) |
| `prismadata__routing_isochrone__modo` | string | sim | Qual dimensao foi limitada: 'tempo' ou 'distancia'. |
| `prismadata__routing_isochrone__limite_tempo_s` | integer \| null | sim | Limite de tempo em segundos. Null quando modo='distancia'. |
| `prismadata__routing_isochrone__limite_distancia_m` | integer \| null | sim | Limite de distancia em metros. Null quando modo='tempo'. |
| `prismadata__routing_isochrone__perfil` | string | sim | Perfil utilizado (car, foot, bike) |
| `prismadata__routing_isochrone__sentido` | string | sim | Sentido do movimento (INDO, SAINDO) |
| `prismadata__routing_isochrone__area_m2` | number | sim | Area do poligono em metros quadrados |
| `prismadata__routing_isochrone__condicao_transito` | string | sim | Nivel de trânsito pedido: livre \| normal \| pico_moderado \| pico_pesado. |
| `prismadata__routing_isochrone__fator_temporal` | number | sim | Multiplicador aplicado ao time_limit (1.0=livre, 0.7=normal, 0.5=pico_moderado, 0.3=pico_pesado). |
| `prismadata__routing_isochrone__limite_tempo_s_efetivo` | integer \| null | sim | time_limit efetivamente enviado ao motor de roteamento (time_limit * fator, mín. 60s). |
| `prismadata__routing_isochrone__municipio_ibge` | integer \| null | sim | Código IBGE do município identificado (observabilidade; não afeta o fator). |

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

---

### `POST /routing/batch/isochrone`

Calcula multiplas isocronas em batch.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/routing/batch/isochrone" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "items": [
           {
             "lat": -19.9323,
             "lng": -43.9351,
             "time_limit": 600,
             "condicao_transito": "normal"
           }
         ],
         "profile": "car",
         "sentido": "SAINDO"
       }'
```

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

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `items` | array[object] | sim | Lista de isocronas a calcular |
| `profile` | string | não | Perfil de roteamento |
| `sentido` | string | não | SAINDO (do ponto) ou INDO (para o ponto) |

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

> Operacao realizada com sucesso

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

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

---

### `GET /routing/buffer`

Buffer circular geodesico (distancia euclidiana, sem malha viaria).

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/routing/buffer?lat=-19.9323&lng=-43.9351&raio_m=500" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: num_vertices=64
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude do centro (WGS84). |
| `lng` | query | number | sim | Longitude do centro (WGS84). |
| `raio_m` | query | integer | sim | Raio euclidiano em metros (10..100000). Cap em 100 km — acima disso nao e buffer, e analise regional. |
| `num_vertices` | query | integer | não | Numero de vertices do poligono aproximando o circulo. 64 = ~99.5% da area real, suficiente pra maioria dos usos. |

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

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__routing_isochrone__geometria` | string | sim | Poligono WKT do circulo. |
| `prismadata__routing_isochrone__area_m2` | integer | sim | Area do circulo em m² (WGS84). |
| `prismadata__routing_isochrone__raio_m` | integer | sim | Raio ecoado do request (m). |
| `prismadata__routing_isochrone__num_vertices` | integer | sim | Numero de vertices do poligono aproximando o circulo. |
| `prismadata__routing_isochrone__centro_lat` | number | sim | Latitude do centro. |
| `prismadata__routing_isochrone__centro_lng` | number | sim | Longitude do centro. |

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

---

### `POST /routing/batch/buffer`

Calcula multiplos buffers em batch.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/routing/batch/buffer" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "items": [
           {
             "lat": -19.9323,
             "lng": -43.9351,
             "raio_m": 500,
             "num_vertices": 64
           }
         ]
       }'
```

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

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `items` | array[object] | sim | Lista de buffers a calcular |

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

> Operacao realizada com sucesso

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `TOTAL` | integer | sim | Total de buffers solicitados. |
| `SUCESSOS` | integer | sim | Quantidade gerada com sucesso. |
| `FALHAS` | integer | sim | Quantidade que falhou. |
| `RESULTADOS` | array[object] | sim | Lista de resultados. |

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

---

## Recursos relacionados

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