> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.
# IBGE
> As estatísticas oficiais do Brasil, do IBGE: encontre qualquer uma das mais de 9.000 tabelas (desocupação e rendimento da PNAD Contínua, inflação pelo IPCA, PIB dos Municípios, Censo 2022) e leia seus valores por país, região, estado ou município.
O Instituto Brasileiro de Geografia e Estatística (IBGE) publica as
estatísticas oficiais do Brasil como tabelas agregadas: mais de 9.000, de
cerca de 70 pesquisas e censos. A PNAD Contínua para desocupação,
rendimento e informalidade; o IPCA e o INPC para a inflação; o PIB dos
Municípios; o Censo Demográfico 2022 para cada município; pesquisas
agropecuárias e industriais.
Pesquise o catálogo por palavras, pesquisa, assunto, periodicidade ou nível
territorial para encontrar uma tabela e suas variáveis, e depois leia seus
valores para os períodos e territórios de que precisa. Os territórios usam
os códigos do próprio IBGE: o código de 2 dígitos da UF e o de 7 dígitos do
município, o mesmo que outras fontes brasileiras trazem como
`municipality_code`.
## Pesquisar tabelas
`POST /br/ibge/tables-search/v1` Dataset
Encontra tabelas por palavras, pesquisa, assunto, periodicidade ou nível territorial.
| Campo | Tipo | Notas |
| - | - | - |
| `query` | string | Opcional. Palavras do título, da pesquisa, do assunto ou das variáveis da tabela, p. ex. `taxa de desocupação`. |
| `survey` | string | Opcional. O `survey_id` de dois caracteres da pesquisa (p. ex. `DD` PNAD Contínua trimestral, `IA` IPCA, `CD` Censo Demográfico) ou o nome completo. |
| `subject` | string | Opcional. O assunto como o IBGE o nomeia, p. ex. `Trabalho`, `Índices de preços`. Maiúsculas e acentos são ignorados. |
| `periodicity` | string | Opcional. `monthly`, `quarterly`, `annual`, ou outra periodicidade que um resultado mostre. |
| `territory_level` | enum | Opcional. Só tabelas com dados no nível `country`, `region`, `state` ou `municipality`. |
| `table_id` | string | Opcional. Uma tabela pelo número, p. ex. `4099`. |
| `page` | integer | Opcional. Página, a partir de 1. Por padrão `1`. |
| `per_page` | integer | Opcional. Tabelas por página, 1-20. Por padrão `10`. |
```bash theme={"dark"}
curl https://api.croma.run/br/ibge/tables-search/v1 \
-H "Authorization: Bearer $CROMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "taxa de desocupação",
"territory_level": "state",
"per_page": 5
}'
```
Cada tabela é `{ table_id, name, survey_id, survey, subject, periodicity, period_start, period_end, territory_levels, variables, classifications, source_url }`.
* `variables`: `{ variable_id, name, unit }`; passe os ids para `ibge-table-values` em `variable_ids`.
* `classifications`: as desagregações que a tabela oferece (sexo, faixa etária, produto, seção da CNAE...), cada uma `{ classification_id, name, categories }`, cada categoria `{ category_id, name, level }` (`level` 0 é o total). Passe-as para `ibge-table-values` em `classifications`.
* `territory_levels`: `country`, `region`, `state`, `municipality`, e níveis mais finos ou especiais como `metro_area`, `mesoregion` ou `microregion`.
* `period_start` e `period_end`: os códigos de período que a tabela cobre, `yyyy` nas tabelas anuais, `yyyymm` nas mensais, `yyyy0q` nas trimestrais (`202602` é o segundo trimestre de 2026).
## Valores de uma tabela
`POST /br/ibge/table-values/v1` Retorna os valores de uma tabela para as variáveis, períodos, territórios e categorias pedidos.
| Campo | Tipo | Notas |
| - | - | - |
| `table_id` | string | **Obrigatório.** O número da tabela, p. ex. `4099` (taxa de desocupação da PNAD Contínua). A pesquisa acima o encontra. |
| `variable_ids` | string | Opcional. Números de variável separados por vírgula, p. ex. `4099`. Vazio retorna todas as variáveis da tabela. |
| `period` | string | Opcional. `latest`, um período (`2023`, `202609` para um mês, `202602` para um trimestre) ou um intervalo, p. ex. `202401-202604`. Por padrão `latest`. |
| `territory_level` | enum | Opcional. `country`, `region`, `state` ou `municipality`. A tabela precisa ter dados nesse nível. Por padrão `country`. |
| `territory_code` | string | Opcional. Códigos IBGE separados por vírgula: os 2 dígitos de uma UF (`35`), os 7 de um município (`3550308`). Vazio retorna todos os territórios do nível. |
| `classifications` | string | Opcional. Pares `classificação:categorias` separados por `;`, p. ex. `315:7170,7171` ou `2:all`. Uma classificação omitida retorna o seu total. |
```bash theme={"dark"}
curl https://api.croma.run/br/ibge/table-values/v1 \
-H "Authorization: Bearer $CROMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"table_id": "4099",
"variable_ids": "4099",
"period": "latest",
"territory_level": "country"
}'
```
Retorna `found`, o `table_name`, `survey` e `periodicity` da tabela, os `periods` cobertos (`{ period, name }`), as `variables` (`{ variable_id, name, unit }`), `count` e `values`. Cada valor é `{ territory_level, territory_code, territory_name, variable_id, period, value, value_note, unit, categories }`.
* `value`: um número, ou null quando o IBGE não publica nenhum para aquela célula. `value_note` diz então por quê: `not_applicable`, `not_available` ou `suppressed` (omitido para proteger os informantes). Um zero verdadeiro é `0` com `value_note: "zero"`.
* `categories`: a categoria de cada classificação a que o valor pertence, `{ classification_id, category_id, category_name }`. Uma classificação não pedida volta com o seu total.
* `found` é false, sem valores, quando a tabela não existe ou não tem nada para o período pedido.
Uma chamada retorna no máximo 15.000 valores (territórios x variáveis x
períodos x categorias). Um pedido maior é recusado com
`too_many_results`: restrinja `territory_code`, `variable_ids`, `period` ou
`classifications`, ou divida-o.
Esquemas, todos os campos de resposta e um playground interativo.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.