---
title: "IBGE Statistical Table Values"
method: POST
path: "/br/ibge/table-values/v1"
tags: ["Brazil", "IBGE"]
---

# IBGE Statistical Table Values

`POST /br/ibge/table-values/v1`

## Request

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

Read the values of one of IBGE's statistical tables for Brazil: unemployment (table 4099), IPCA inflation (7060), municipal GDP (5938), Censo 2022 population (4709) and 9,000+ more. Choose the variables, the period (`latest`, one period or a range), the territorial level (country, region, state, municipality) with optional IBGE territory codes, and classification categories. Each value comes with its territory, period, unit and categories. Up to 15,000 values per call.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `table_id` string, required: The table's number, e.g. `4099` (unemployment, PNAD Contínua). `ibge-tables-search` finds it.
  - `variable_ids` string: The variables to return, by number and separated by commas, e.g. `4099` or `4099,4114`. Empty returns every variable of the table (optional).
  - `period` string: `latest` (the most recent period the table has), one period (`2023` for a year, `202609` for a month, `202602` for the second quarter of 2026), or a range of them, e.g. `202401-202604`.
  - `territory_level` 'country' | 'region' | 'state' | 'municipality': The territorial level of the values: `country` (Brazil), `region` (the five Grandes Regiões), `state` (the 27 UFs) or `municipality`.
  - `territory_code` string: IBGE codes of the territories, separated by commas: a region's 1 digit, a state's 2 (e.g. `35` São Paulo) or a municipality's 7 (e.g. `3550308` São Paulo). Empty returns every territory of the level (optional).
  - `classifications` string: Breakdowns to return, as `classification:categories`, several separated by `;`, e.g. `315:7170,7171` (two IPCA groups) or `2:all` (every category of classification 2). A classification left out returns its total (optional).

## Response `200`

Successful response

- IbgeTableValuesResponse
  - `data` IbgeTableValuesData, required
    - `found` boolean, required: false when the table does not exist or has no values for this request.
    - `table_id` string, required
    - `table_name` string, nullable, required
    - `survey` string, nullable, required
    - `periodicity` string, nullable, required
    - `territory_level` 'country' | 'region' | 'state' | 'municipality', required
    - `period` string, required: The period asked for, echoed back.
    - `periods` object[], required: The periods the values cover, oldest first.
      - `period` string, required
      - `name` string, required: The period as IBGE names it, e.g. `2º trimestre 2026`.
    - `variables` object[], required: The variables the values belong to.
      - `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`.
    - `count` integer, required
    - `values` object[], required
      - `territory_level` 'country' | 'region' | 'state' | 'municipality', required
      - `territory_code` string, required: The territory's IBGE code: `1` for Brazil, 1 digit for a region, 2 for a state, 7 for a municipality.
      - `territory_name` string, required
      - `variable_id` string, required
      - `period` string, required: The period's code, e.g. `202602` or `2023`; its name is in `periods`.
      - `value` number, nullable, required: The value, or null when IBGE publishes none for this cell (see `value_note`).
      - `value_note` 'zero' | 'not_applicable' | 'not_available' | 'suppressed', nullable, required: Why a value is special: `zero` (a true zero), `not_applicable`, `not_available`, or `suppressed` (withheld to protect respondents).
      - `unit` string, nullable, required
      - `categories` object[], required: The category of each classification this value belongs to.
        - `classification_id` string, required
        - `category_id` string, required
        - `category_name` string, required
    - `source_url` string, nullable, required
    - `checked_at` string, required: When this answer was read from IBGE, as an ISO timestamp.

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an 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)