# Formato de Resposta

## Convenção de nomes

Todos os campos de resposta seguem o padrão `prismadata__<serviço>__<campo>`, facilitando a identificação da origem de cada dado.

## Prefixos por serviço

| Serviço | Prefixo | Exemplo |
|---------|---------|--------|
| Geocoder | `prismadata__geocoder__` | `prismadata__geocoder__latitude` |
| Favelas | `prismadata__slum__` | `prismadata__slum__favela_nome` |
| Renda Estática | `prismadata__personal_income_static__` | `prismadata__personal_income_static__percentil_br` |
| Renda PDF | `prismadata__personal_income_pdf__` | `prismadata__personal_income_pdf__mean` |
| Presídios | `prismadata__prison__` | `prismadata__prison__nome_estabelecimento` |
| Fronteiras | `prismadata__border__` | `prismadata__border__faixa_fronteira` |
| InfoSC | `prismadata__infosc__` | `prismadata__infosc__cod_setor` |
| Rotas | `prismadata__routing_route__` | `prismadata__routing_route__distancia_m` |
| Isocronas | `prismadata__routing_isochrone__` | `prismadata__routing_isochrone__geometria` |
| Validação de Endereços | `prismadata__addr_validation__` | `prismadata__addr_validation__score` |

## Tipos de resposta

### Objeto único (GET)

Endpoints GET retornam um objeto JSON plano com os campos do serviço:

```json
{
  "prismadata__prison__nome_estabelecimento": "Unidade Penal X",
  "prismadata__prison__distancia_borda_m": 1010.79,
  "prismadata__prison__uf": "MS"
}
```

### Dicionário indexado (batch POST)

Endpoints batch retornam um dicionário onde as **chaves são os identificadores enviados na requisição** e os valores são os objetos de resposta:

```json
{
  "ponto_1": { "prismadata__prison__nome_estabelecimento": "...", ... },
  "ponto_2": { "prismadata__prison__nome_estabelecimento": "...", ... }
}
```

**Exceção — lotes de roteamento** (`POST /routing/batch/route`, `/routing/batch/isochrone`, `/routing/batch/buffer`): a resposta traz contadores e a lista de resultados, no formato `{"TOTAL": int, "SUCESSOS": int, "FALHAS": int, "RESULTADOS": [...]}`. Consulte o schema de cada endpoint para o formato de cada item.

**Exceção — `POST /location/entorno/agregado/batch`**: as chaves de primeiro nível vêm prefixadas (`prismadata__entorno__<id>`) e cada item traz o envelope completo `{SUCESSO, EXCEPTION, OUTPUT, STATS}`. Um item com falha volta com `SUCESSO=false` sem derrubar o lote:

```json
{
  "prismadata__entorno__loja_1": { "SUCESSO": true, "EXCEPTION": "", "OUTPUT": { ... }, "STATS": { ... } },
  "prismadata__entorno__loja_2": { "SUCESSO": false, "EXCEPTION": "...", "OUTPUT": {}, "STATS": {} }
}
```

## Valores nulos

Quando um ponto está fora da área de cobertura de um serviço, os campos de detalhe retornam `null`. Isso indica ausência de dados, não um erro.

Porém, **indicadores de proximidade ou pertencimento podem ter valor** mesmo quando os campos de detalhe são `null`. Exemplo para um ponto longe de qualquer presídio:

```json
{
  "prismadata__prison__ponto_dentro_presidio": false,
  "prismadata__prison__distancia_borda_m": 85000.5,
  "prismadata__prison__nome_estabelecimento": null,
  "prismadata__prison__uf": null,
  "prismadata__prison__tipo_estabelecimento": null
}
```

O padrão é: campos booleanos e de distância indicam **relação espacial** e geralmente têm valor; campos de detalhe (nome, tipo, UF) dependem de haver uma entidade próxima o suficiente.

## Content-Type

Todas as respostas utilizam `Content-Type: application/json`.

## Headers de resposta

Todas as respostas incluem os headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. Veja a seção **Rate Limiting & Quota** para detalhes.

---

- Índice geral: https://prismadata.io/llms.txt
- Documentação Redoc interativa: https://prismadata.io/redoc.html