# NewDataCompany API — Liquid Router

> API de dados públicos brasileiros otimizada para LLMs.
> URLs semânticas com ordem livre de conceitos via Knowledge Graph.

## Como funciona

Toda consulta é feita em `GET http://llm.newdatacompany.com/d/{{conceitos}}`. Os segmentos da URL são
tokenizados, normalizados e cruzados contra um Knowledge Graph (Neo4j) para
encontrar o dataset mais relevante. A **ordem dos segmentos não importa**:

```
/d/pib/sp/2021  ==  /d/sp/2021/pib  ==  /d/2021/pib/sp
```

Os conceitos são divididos em 4 categorias:

| Categoria   | Exemplos                            |
|-------------|-------------------------------------|
| Métricas    | `pib`, `ideb`, `arrecadacao`        |
| Localizações| `sp`, `sao-paulo`, `rio-de-janeiro` |
| Anos        | `2020`, `2021`, `2022`              |
| Organizações| `ibge`, `inep`, `rf`                |

## Formatos de resposta

Use `?format=` para escolher:

| Formato    | Descrição                            | Content-Type       |
|------------|--------------------------------------|--------------------|
| `markdown` | Tabela com frontmatter YAML (padrão) | `text/plain`       |
| `json`     | Metadados completos da busca         | `application/json` |
| `csv`      | Dados tabulares puros                | `text/csv`         |
| `python`   | Código `pd.read_csv(url)` pronto     | `text/plain`       |

Use `?limit=N` para controlar o número de linhas (1-1000, padrão 100).

## Datasets disponíveis

### Dados municipais

| Slug              | Dataset                     | Métricas principais                         |
|-------------------|-----------------------------|---------------------------------------------|
| `pib`             | PIB Municipal (IBGE)        | pib, impostos, va_agropecuaria, va_industria |
| `pib-per-capita`  | PIB per Capita              | pib_per_capita, populacao                    |
| `populacao`       | Censo 2022 (IBGE)           | populacao, domicilios, area                  |
| `ideb`            | IDEB Municipal (INEP)       | ideb, taxa_aprovacao, nota_saeb              |
| `alfabetizacao`   | Avaliação Alfabetização     | taxa_alfabetizacao                           |
| `seguranca-publica` | Segurança Municipal (FBSP)| feminicidio, homicidio_doloso                |
| `saude`           | Saúde Municipal (IEPS)      | tx_med, leitos_uti_sus                       |
| `desmatamento`    | Desmatamento (INPE/PRODES)  | desmatado, vegetacao_natural                 |
| `transparencia`   | Transparência (CGU/EBT)     | nota, ranking                                |
| `saneamento`      | Saneamento (ANA)            | carga_gerada, populacao_atendida             |
| `emendas-parlamentares` | Emendas (CGU)         | valor_pago, valor_empenhado                  |

### Dados estaduais (UF)

| Slug              | Dataset                     | Métricas principais                          |
|-------------------|-----------------------------|----------------------------------------------|
| `arrecadacao`     | Arrecadação Federal (RF)    | irpf, cofins, itr, iof, csll                 |
| `siconfi`         | Despesas Orçamentárias (ME) | valor por conta_bd e estagio_bd              |
| `seguranca-uf`    | Segurança UF (FBSP)         | morte_violenta, feminicidio, roubo_veiculo   |
| `saude-uf`        | Saúde UF (IEPS)             | cobertura_atencao_basica, tx_hosp_csap       |
| `ideb-uf`         | IDEB Estadual (INEP)        | ideb, taxa_aprovacao, nota_saeb              |

## Aliases reconhecidos

O sistema normaliza variações automaticamente:

| Você pode usar                    | Resolve para        |
|-----------------------------------|---------------------|
| `educacao`, `escola`, `ensino`    | `ideb`              |
| `economia`, `gdp`                | `pib`               |
| `habitantes`, `pop`, `censo`     | `populacao`         |
| `imposto`, `receita-federal`     | `arrecadacao`       |
| `despesas`, `orcamento`          | `siconfi`           |
| `violencia`, `criminalidade`     | `seguranca-publica` |
| `esgoto`                         | `saneamento`        |
| `prodes`, `floresta`             | `desmatamento`      |
| `medicos`, `uti`, `leitos`       | `saude`             |

Estados aceitam sigla (`sp`) ou nome completo (`sao-paulo`).

## Filtros especiais (SICONFI)

O dataset SICONFI suporta filtros por função orçamentária via URL:

```
/d/siconfi/saude/sp/2021       → Despesas com Saúde
/d/siconfi/educacao/rj/2020    → Despesas com Educação
/d/siconfi/seguranca-publica   → Despesas com Segurança Pública
```

## Multi-dataset

Quando a URL contém métricas de domínios diferentes, a API retorna
múltiplos datasets na mesma resposta:

```
/d/pib/ideb/sp/2021  → PIB + IDEB de São Paulo em 2021
```

## Exemplos de consultas

```
GET http://llm.newdatacompany.com/d/pib/sp/2021                → PIB de São Paulo em 2021
GET http://llm.newdatacompany.com/d/arrecadacao/2022           → Arrecadação federal de 2022
GET http://llm.newdatacompany.com/d/ideb/rj/2019/2021          → IDEB do RJ de 2019 a 2021
GET http://llm.newdatacompany.com/d/seguranca-uf/2020          → Segurança pública por UF em 2020
GET http://llm.newdatacompany.com/d/siconfi/saude/sp           → Gastos com saúde de SP (SICONFI)
GET http://llm.newdatacompany.com/d/populacao/mg?format=csv    → População de MG em CSV
GET http://llm.newdatacompany.com/d/pib/sp?format=python       → Código Python pronto para uso
```

## Endpoints auxiliares

| Endpoint              | Descrição                          |
|-----------------------|------------------------------------|
| `/llms.txt`           | Esta página (onboarding para LLMs) |
| `/catalog`            | Catálogo dinâmico com dados do grafo|
| `/catalog/json`       | Catálogo em JSON                   |
| `/api/v1/health`      | Status da API                      |
| `/api/v1/health/ready`| Readiness check                    |

## Instruções para LLMs

1. Use esta página (`/llms.txt`) para entender a API antes de fazer consultas.
2. Comece com a métrica desejada (ex: `pib`, `ideb`, `arrecadacao`).
3. Adicione filtros de localização (`sp`, `rj`) e ano (`2021`).
4. Use `?format=json` para obter metadados estruturados.
5. Use `?format=csv` para ingerir dados diretamente.
6. Use `?format=python` para gerar código de análise.
7. Se receber 404, simplifique a consulta (menos termos).
8. Consulte `/catalog/json` para ver datasets disponíveis dinamicamente.