ibger: Access the 'IBGE' Aggregate Data API from 'R'

Description

'Tidyverse'-friendly interface to the Brazilian Institute of Geography and Statistics ('IBGE') aggregate data 'API' https://servicodados.ibge.gov.br/api/docs/agregados?versao=3. Query aggregates, variables, localities, periods, and metadata from surveys and censuses conducted by 'IBGE'.

Author(s)

Maintainer: Andre Leite leite@castlab.org

Authors:

• Marcos Wasilew marcos.wasilew@gmail.com

• Hugo Vasconcelos hugo.vasconcelos@ufpe.br

• Carlos Amorin carlos.agaf@ufpe.br

• Diogo Bezerra diogo.bezerra@ufpe.br

See Also

Useful links:

• https://github.com/StrategicProjects/ibger

• Report bugs at https://github.com/StrategicProjects/ibger/issues

Fetch data from a SIDRA API URL

Description

Parses a SIDRA API URL and fetches the data using ibge_variables(), returning the same tidy tibble format.

Usage

fetch_sidra_url(url, validate = TRUE)

Arguments

Value

A tibble in tidy (long) format, same as ibge_variables().

Examples

## Not run: 
url <- "https://apisidra.ibge.gov.br/values/t/7060/n1/all/v/63/p/last%2012/c315/7169"
fetch_sidra_url(url)

# Pipe-friendly: inspect then fetch
url |> parse_sidra_url()
url |> fetch_sidra_url()

## End(Not run)

List IBGE aggregates

Description

Retrieves the set of available aggregates (tables), grouped by survey. Each aggregate corresponds to a SIDRA table. Results are cached in memory per unique combination of parameters, so repeated calls with the same filters are instant.

Usage

ibge_aggregates(
  period = NULL,
  subject = NULL,
  classification = NULL,
  periodicity = NULL,
  level = NULL
)

Arguments

Value

A tibble with columns: survey_id, survey_name, aggregate_id, aggregate_name

Examples

## Not run: 
ibge_aggregates()
ibge_aggregates(periodicity = "P5")
ibge_aggregates(level = "N6")

## End(Not run)

Clear metadata cache

Description

Removes all cached metadata (aggregates and surveys), forcing fresh API calls on subsequent requests.

Usage

ibge_clear_cache()

Value

No return value, called for side effects.

Interactive aggregate explorer

Description

Launches a Shiny app for browsing and filtering the full catalog of IBGE aggregates. The app displays value boxes with summary counts, a searchable table with column-level filters, and lets you filter by survey or search aggregate names.

Usage

ibge_explorer(launch.browser = TRUE)

Arguments

Details

Clicking a row shows a notification with the aggregate ID and the corresponding ibge_metadata() call. A CSV download button is also available.

Value

This function is called for its side effect (launching the app). Returns the value of shiny::runApp() invisibly.

Examples

## Not run: 
# Open in RStudio Viewer
ibge_explorer(launch.browser = FALSE)

# Open in browser
ibge_explorer()

## End(Not run)

Localities for an aggregate

Description

Retrieves available localities for an aggregate at one or more geographic levels. Validates the requested level(s) against the aggregate metadata before querying.

Usage

ibge_localities(aggregate, level = "N6", validate = TRUE)

Arguments

Value

A tibble with columns: id, name, level_id, level_name

Examples

## Not run: 
ibge_localities(1437, level = "N1")
ibge_localities(1437, level = c("N6", "N7"))

## End(Not run)

Metadata for an aggregate

Description

Retrieves complete metadata for an aggregate: name, survey, subject, periodicity, territorial levels, variables, and classifications with all their categories.

Usage

ibge_metadata(aggregate)

Arguments

Value

A list of class ibge_metadata with:

• id, name, url, survey, subject

• periodicity: list with frequency, start and end

• territorial_level: list with administrative, special and ibge

• variables: tibble with id, name, unit

• classifications: tibble with id, name and list-column categories, where each element is a tibble with category_id, category_name, category_unit and category_level

Examples

## Not run: 
meta <- ibge_metadata(7060)
meta$variables
meta$classifications
tidyr::unnest(meta$classifications, categories)

## End(Not run)

Periods for an aggregate

Description

Retrieves available periods for an aggregate.

Usage

ibge_periods(aggregate)

Arguments

Value

A tibble with columns: id, literal, modification

Examples

## Not run: 
ibge_periods(1705)

## End(Not run)

IBGE subject codes lookup

Description

Returns a tibble with IBGE subject (theme) codes and descriptions. These codes can be used to understand the thematic organization of IBGE surveys and aggregates.

Usage

ibge_subjects(pattern = NULL, ignore_case = TRUE)

Arguments

Details

The table is built-in (no API call is made) and contains all subject codes currently defined by IBGE.

Value

A tibble with columns:

id

Integer subject code.

name

Character subject description.

Examples

# All subjects
ibge_subjects()

# Find sanitation-related themes
ibge_subjects("saneamento|esgoto|lixo")

# Find themes mentioning "internet"
ibge_subjects("internet")

Get survey metadata for a specific period

Description

Retrieves detailed institutional and methodological metadata for a survey in a given reference period. Before querying, both the survey code and the year/month combination are validated against the IBGE catalog, so invalid inputs produce clear errors without wasting an API call.

Usage

ibge_survey_metadata(survey, year, month = NULL, order = 0)

Arguments

Details

The structure of occurrences varies by survey and may include fields such as objective, data collection method, sample design, geographic scope, reference period, and more.

Value

A list of class ibge_survey_metadata with:

status

Survey status (corrente, concluída, desativada, etc.)

category

conjuntural or estrutural

type

Type of statistical operation

area

Responsible area

acronym

Survey acronym

start_date

Survey start date

deactivation_date

Deactivation date, if applicable

sidra_url

URL to SIDRA data

concla_url

URL to CONCLA (CNAE classifications)

thematic_classifications

Tibble of thematic classifications

occurrences

List of metadata records for the period (structure varies by survey)

See Also

ibge_surveys(), ibge_survey_periods()

Examples

## Not run: 
# Structural survey (no month needed)
ibge_survey_metadata("CD", year = 2022)

# Conjunctural survey (specify month)
ibge_survey_metadata("SC", year = 2023, month = 6)

# Inspect methodology fields
meta <- ibge_survey_metadata("CD", year = 2022)
names(meta$occurrences[[1]])

# Invalid code: clear error with suggestions
ibge_survey_metadata("PMS", year = 2024)
#> Error: Survey code "PMS" not found in the IBGE catalog.

# Invalid year: error with available range
ibge_survey_metadata("CD", year = 1800)
#> Error: Year 1800 not available for survey "CD".
#> i Available years: 1940 to 2022 (9 total).

## End(Not run)

List periods with metadata for a survey

Description

Retrieves the periods (year/month combinations) for which a given survey has associated metadata records. Before querying, the survey code is validated against the IBGE catalog; invalid codes produce a helpful error with suggestions.

Usage

ibge_survey_periods(survey)

Arguments

Value

A tibble with columns:

year

Integer year with metadata available.

month

Integer month (1–12) or NA for structural (annual or longer) surveys.

order

Publication order within the period (0 = most recent).

See Also

ibge_surveys(), ibge_survey_metadata()

Examples

## Not run: 
# Conjunctural survey (monthly periods)
ibge_survey_periods("SC")   # Pesquisa Mensal de Serviços

# Structural survey (annual periods)
ibge_survey_periods("CD")   # Censo Demográfico

# Invalid code: helpful error with suggestions
ibge_survey_periods("PMS")
#> Error: Survey code "PMS" not found in the IBGE catalog.
#> i Did you mean one of these?
#>   * SC - Pesquisa Mensal de Serviços
#>   ...

## End(Not run)

List IBGE surveys with metadata

Description

Retrieves the full catalog of IBGE surveys (statistical operations) that have associated metadata in the IBGE Metadata API, including status, category, collection and publication frequency, and thematic classifications.

Usage

ibge_surveys(thematic_classifications = TRUE)

Arguments

Details

This function queries a different API from the other ⁠ibge_*⁠ functions. While ibge_aggregates() and ibge_metadata() use the Aggregates API (v3), this function uses the Metadata API (v2), which provides institutional and methodological documentation about surveys.

Value

A tibble with columns:

id

Survey code (e.g. "SC", "CD")

name

Survey name in Portuguese

name_en

Survey name in English (may be NA)

status

Survey status: Ativa, Encerrada, etc.

category

Conjuntural, Estrutural, or Especial

collection_frequency

Data collection frequency (Mensal, Anual, etc.)

publication_frequency

Publication frequency

thematic_classifications

List-column of tibbles with thematic classification details (name, domain, description). Only if thematic_classifications = TRUE.

See Also

ibge_survey_periods(), ibge_survey_metadata()

Examples

## Not run: 
# Full catalog
ibge_surveys()

# Flat table without classifications
ibge_surveys(thematic_classifications = FALSE)

# Filter active conjunctural surveys
library(dplyr)
ibge_surveys(thematic_classifications = FALSE) |>
  filter(status == "Ativa", category == "Conjuntural")

## End(Not run)

Get variable data from an aggregate

Description

Main function of the package. Retrieves variable results from an IBGE aggregate for the specified localities, periods and classifications.

Usage

ibge_variables(
  aggregate,
  variable = NULL,
  periods = -6,
  localities = "BR",
  classification = NULL,
  view = NULL,
  validate = TRUE
)

Arguments

Details

Before querying the API, validates all parameters against the aggregate metadata. If any parameter is invalid, stops with a clear error message showing the allowed values.

Value

A tibble in tidy (long) format with columns: variable_id, variable_name, variable_unit, classification columns (when present), locality_id, locality_name, locality_level, period, value

Examples

## Not run: 
# IPCA in Brazil
ibge_variables(7060, localities = "BR")

# Specific variables for states
ibge_variables(1705, variable = c(284, 285), localities = "N3")

# Specific municipalities with classification
ibge_variables(
  aggregate      = 1712,
  variable       = 214,
  periods        = -3,
  localities     = list(N6 = c(3550308, 3304557)),
  classification = list("226" = c(4844, 96608))
)

## End(Not run)

Parse IBGE value column

Description

Converts the character value column returned by ibge_variables() to numeric, handling IBGE special value conventions.

Usage

parse_ibge_value(x)

Arguments

Details

According to IBGE's tabular presentation standards, the value column may contain special character codes instead of numbers:

Value

A numeric vector where:

• "-" becomes 0

• "..", "..." and "X" become NA_real_

• All other values are converted with as.numeric()

Examples

parse_ibge_value(c("1.5", "10", "-", "..", "...", "X", NA))
#> [1] 1.5  10.0  0.0   NA    NA    NA    NA

## Not run: 
# Typical usage after ibge_variables()
library(dplyr)

ibge_variables(7060, localities = "BR") |>
  mutate(value = parse_ibge_value(value))

## End(Not run)

Parse a SIDRA API URL into ibger parameters

Description

Converts a SIDRA API URL (from the SIDRA Query Builder or sidrar package) into a human-readable breakdown of its parameters, enriched with names from the aggregate metadata.

Usage

parse_sidra_url(url)

Arguments

Value

A list of class sidra_query with:

• aggregate: list with id and name

• variables: tibble with id and name

• periods: character vector of period codes

• localities: list of level/locality pairs

• classifications: list of classification/category details

• ibger_call: string with the equivalent ibge_variables() call

Examples

## Not run: 
url <- "https://apisidra.ibge.gov.br/values/t/5434/n1/all/v/4090/p/last%201/c888/47946,56623"
parse_sidra_url(url)

## End(Not run)