> ## 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

> Brazil's official statistics from IBGE: find any of its 9,000+ tables (PNAD Contínua unemployment and income, IPCA inflation, municipal GDP, Censo 2022) and read their values by country, region, state or municipality.

The Instituto Brasileiro de Geografia e Estatística (IBGE) publishes
Brazil's official statistics as aggregate tables: more than 9,000 of them,
from some 70 surveys and censuses. PNAD Contínua for unemployment, income
and informality; IPCA and INPC for inflation; PIB dos Municípios; Censo
Demográfico 2022 for every municipality; agricultural and industrial
surveys.

Search the catalog by words, survey, subject, periodicity or territorial
level to find a table and its variables, then read its values for the
periods and territories you need. Territories use IBGE's own codes: the
2-digit state code and the 7-digit municipality code other Brazilian
sources carry as `municipality_code`.

## Search tables

`POST /br/ibge/tables-search/v1` <a className="dataset-pill" href="/datasets">Dataset</a>

Finds tables by words, survey, subject, periodicity or territorial level.

| Field | Type | Notes |
| - | - | - |
| `query` | string | Optional. Words in the table's title, survey, subject or variables, in Portuguese, e.g. `taxa de desocupação`. |
| `survey` | string | Optional. The survey's two-character `survey_id` (e.g. `DD` PNAD Contínua trimestral, `IA` IPCA, `CD` Censo Demográfico) or its full name. |
| `subject` | string | Optional. The subject as IBGE names it, e.g. `Trabalho`, `Índices de preços`. Case and accents are ignored. |
| `periodicity` | string | Optional. `monthly`, `quarterly`, `annual`, or a rarer periodicity a search result shows. |
| `territory_level` | enum | Optional. Only tables with data at `country`, `region`, `state` or `municipality` level. |
| `table_id` | string | Optional. One table by its number, e.g. `4099`. |
| `page` | integer | Optional. 1-based page. Default `1`. |
| `per_page` | integer | Optional. Tables per page, 1-20. Default `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
      }'
```

Each table is `{ table_id, name, survey_id, survey, subject, periodicity, period_start, period_end, territory_levels, variables, classifications, source_url }`.

* `variables`: `{ variable_id, name, unit }`; pass the ids to `ibge-table-values` in `variable_ids`.
* `classifications`: the breakdowns the table offers (sex, age group, product, CNAE section...), each `{ classification_id, name, categories }`, every category `{ category_id, name, level }` (`level` 0 is the total). Pass them to `ibge-table-values` in `classifications`.
* `territory_levels`: `country`, `region`, `state`, `municipality`, and finer or special levels such as `metro_area`, `mesoregion` or `microregion`.
* `period_start` and `period_end`: the period codes the table covers, `yyyy` for annual tables, `yyyymm` for monthly ones, `yyyy0q` for quarterly ones (`202602` is the second quarter of 2026).

## Table values

`POST /br/ibge/table-values/v1` Returns the values of one table for the variables, periods, territories and categories asked for.

| Field | Type | Notes |
| - | - | - |
| `table_id` | string | **Required.** The table's number, e.g. `4099` (PNAD Contínua unemployment rate). The search above finds it. |
| `variable_ids` | string | Optional. Variable numbers separated by commas, e.g. `4099`. Empty returns every variable of the table. |
| `period` | string | Optional. `latest`, one period (`2023`, `202609` for a month, `202602` for a quarter) or a range, e.g. `202401-202604`. Default `latest`. |
| `territory_level` | enum | Optional. `country`, `region`, `state` or `municipality`. The table must have data at that level. Default `country`. |
| `territory_code` | string | Optional. IBGE codes separated by commas: a state's 2 digits (`35`), a municipality's 7 (`3550308`). Empty returns every territory of the level. |
| `classifications` | string | Optional. `classification:categories` pairs separated by `;`, e.g. `315:7170,7171` or `2:all`. A classification left out returns its 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"
      }'
```

Returns `found`, the table's `table_name`, `survey` and `periodicity`, the `periods` covered (`{ period, name }`), the `variables` (`{ variable_id, name, unit }`), `count` and `values`. Each value is `{ territory_level, territory_code, territory_name, variable_id, period, value, value_note, unit, categories }`.

* `value`: a number, or null when IBGE publishes none for that cell. `value_note` then says why: `not_applicable`, `not_available` or `suppressed` (withheld to protect respondents). A true zero is `0` with `value_note: "zero"`.
* `categories`: the category of each classification the value belongs to, `{ classification_id, category_id, category_name }`. A classification not asked for comes back as its total.
* `found` is false, with no values, when the table does not exist or has nothing for the period asked.

<Note>
  One call returns at most 15,000 values (territories x variables x periods x
  categories). A larger request is refused with `too_many_results`: narrow
  `territory_code`, `variable_ids`, `period` or `classifications`, or split it.
</Note>

<Card title="Full reference" icon="code" href="/api-reference/overview">
  Schemas, all response fields, and an interactive playground.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.