IBGE

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 Dataset 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`.

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.

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.

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.

Full reference

Schemas, all response fields, and an interactive playground.

Get Started

Request types

Monitors

Countries

Search tables

Table values

Full reference

​Search tables

​Table values

Full reference

Search tables

Table values