Understanding the IBGE Aggregate Data API

Aggregates

An aggregate is a specific table of results from an IBGE survey. Each aggregate has a numeric ID that is stable over time. For example:

• 1705 — IPCA-15 — Variação mensal, acumulada no ano, acumulada em 12 meses e peso mensal (Monthly change, year-to-date accumulation, 12-month accumulation and monthly weight)
• 1712 — Produção, venda, valor da produção e área colhida da lavoura (Censo Agropecuário) (Production, sales, production value and harvested area of crops — Agricultural Census)
• 7060 — IPCA — Variação mensal, acumulada no ano, acumulada em 12 meses e peso mensal (Monthly change, year-to-date accumulation, 12-month accumulation and monthly weight)

library(ibger)

# Search for aggregates
ibge_aggregates()

You can filter by periodicity, geographic level, subject, or classification:

# Only quarterly aggregates
ibge_aggregates(periodicity = "P10")

# Aggregates that have state-level data
ibge_aggregates(level = "N3")

Variables

Each aggregate exposes one or more variables — the measures being reported. Aggregate 1712 (crop production), for example, has:

meta <- ibge_metadata(1712)
meta$variables

When calling ibge_variables(), you can request specific variables by ID:

# Two specific variables
ibge_variables(1712, variable = c(214, 1982), localities = "BR")

Use variable = NULL (default) for all standard variables, or variable = "all" to include API-generated percentage variables when available.

Classifications and categories

Besides being linked to a locality and a period, each observation can be further broken down by classifications (dimensions). Each classification contains categories (members).

For aggregate 1712, the classifications are things like “type of product” (226), “producer condition” (218), “economic activity group”, etc. Classification 226 has categories like “pineapple” (4844), “garlic” (96608), “potato” (96609), and hundreds more.

meta <- ibge_metadata(1712)
meta$classifications

# Unnest to see all categories
tidyr::unnest(meta$classifications, categories)

When you don’t specify a classification, the API returns results for the Total category (ID = 0). This is a special aggregate across all categories.

# Default: Total category (aggregated across all products)
ibge_variables(1712, localities = "BR")

# Specific products
ibge_variables(
  1712,
  localities     = "BR",
  classification = list("226" = c(4844, 96608))
)

# All products (can be large)
ibge_variables(
  1712,
  periods        = -1,
  localities     = "BR",
  classification = list("226" = "all")
)

Geographic levels and localities

IBGE organizes Brazil into a hierarchy of geographic levels. Each aggregate supports a specific subset of these levels:

Important: municipality IDs (N6) and metropolitan area IDs (N7) use different numbering. São Paulo city is 3550308 (N6), while the São Paulo metropolitan area is 3501 (N7). Don’t confuse them.

The available levels for each aggregate are in the metadata:

meta <- ibge_metadata(1705)
meta$territorial_level
#> $administrative
#> [1] "N1" "N2" "N3"

You can request all localities at a level, or pick specific ones:

# All states
ibge_variables(1705, localities = "N3")

# Specific states
ibge_variables(1705, localities = list(N3 = c(33, 35)))

The API also supports contextual queries — filtering municipalities by their parent state or region. For example, N6[N3[33,35],N2[1]] means “all municipalities in RJ, SP, or the North region”. ibger passes this through directly:

ibge_variables(
  512,
  variable   = 216,
  periods    = -6,
  localities = "N6[N3[33,35],N2[1]]"
)

Periods and periodicities

Each aggregate has a fixed periodicity:

Period codes encode both the date and periodicity. The code 202001 means different things depending on the aggregate’s periodicity:

• Monthly (P5): January 2020
• Quarterly (P10): Q1 2020
• Semi-annual (P58): S1 2020

The metadata tells you the valid range:

meta <- ibge_metadata(7060)
meta$periodicity
#> $frequency [1] "mensal"
#> $start     [1] "202001"
#> $end       [1] "202512"

ibger’s ibge_periods() lists every individual period:

ibge_periods(7060)