---
title: "IBGE Statistical Tables Search"
method: POST
path: "/br/ibge/tables-search/v1"
tags: ["Brazil", "IBGE"]
---

# IBGE Statistical Tables Search

`POST /br/ibge/tables-search/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/br/ibge/tables-search/v1`
- Auth: HTTP bearer

Search the catalog of Brazil's official statistics from IBGE: 9,000+ aggregate tables from PNAD Contínua, IPCA, PIB dos Municípios, Censo Demográfico and some 70 other surveys. Filter by words in the title, survey or variables, subject, periodicity or territorial level. Each table returns its periodicity, the periods it covers, the levels it has data for (country, region, state, municipality...), its variables with units and its classifications with their categories: everything `ibge-table-values` needs. Refreshed weekly.

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string: Words to find in the table's name, its survey, its subject or its variables, e.g. `desocupação` (optional).
  - `survey` string: The survey, by the two-character `survey_id` a search result returns (e.g. `DD` for PNAD Contínua trimestral, `IA` for IPCA) or by its full name, e.g. `Censo Demográfico`; case and accents ignored (optional).
  - `subject` string: The subject, as IBGE names it, e.g. `Trabalho` or `Índices de preços`; case and accents ignored (optional).
  - `periodicity` string: How often the table is published: `monthly`, `quarterly`, `annual`, and the rarer periodicities a search result shows (optional).
  - `territory_level` '' | 'country' | 'region' | 'state' | 'municipality': Only tables with data at this level: `country`, `region`, `state` or `municipality` (optional).
  - `table_id` string: One table by its number, e.g. `4099` (optional).
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Tables per page (1-20).

## Response `200`

Successful response

- IbgeTablesSearchResponse
  - `data` IbgeTablesSearchData, required
    - `as_of` string, nullable, required: How current the catalog in this response is.
    - `query` string, required
    - `total` number, required: Tables matching the filters, across every page, counted up to 1000.
    - `total_is_exact` boolean, required
    - `page` number, required
    - `per_page` number, required
    - `total_pages` number, required
    - `count` number, required
    - `tables` object[], required
      - `table_id` string, required: The table's number: pass it to `ibge-table-values`.
      - `name` string, required: The table's title, as IBGE publishes it.
      - `survey_id` string, required: IBGE's two-character code for the survey or study.
      - `survey` string, required: The survey or study the table comes from, e.g. `Pesquisa Nacional por Amostra de Domicílios Contínua trimestral`.
      - `subject` string, nullable, required: The subject, as IBGE names it, e.g. `Trabalho`.
      - `periodicity` string, nullable, required: How often the table is published: `monthly`, `quarterly`, `annual`, or a rarer cadence.
      - `period_start` string, nullable, required: The first period the table has, e.g. `201201` (first quarter of 2012) or `2002`.
      - `period_end` string, nullable, required: The last period the table had when the catalog was last read.
      - `territory_levels` string[], required: The levels the table has data for: `country`, `region`, `state`, `municipality`, and finer or special ones such as `metro_area`.
      - `variables` object[], required
        - `variable_id` string, required: The variable's number: pass it in `variable_ids`.
        - `name` string, required: What the variable measures, as IBGE names it.
        - `unit` string, nullable, required: Its unit, e.g. `%`, `Mil Reais`, `Pessoas`.
      - `classifications` object[], required: The breakdowns the table offers (sex, age group, product...) and each one's categories.
        - `classification_id` string, required: The classification's number: the key in `classifications`.
        - `name` string, required
        - `categories` object[], required
          - `category_id` string, required: The category's number: pass it in `classifications`.
          - `name` string, required
          - `level` integer, nullable, required: Depth in the classification's hierarchy: 0 is the total.
      - `source_url` string, required: The table's page at IBGE.

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)