Introduction to sidrar
In sidrar: An Interface to IBGE's SIDRA API

knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>")

Overview

sidrar is an R interface to SIDRA (Sistema IBGE de Recuperação Automática), the system through which the Brazilian Institute of Geography and Statistics (IBGE) publishes aggregate statistics.

The usual workflow is:

find a table with search_sidra();
inspect its available dimensions with info_sidra(); and
retrieve a selection with get_sidra().

Network-dependent examples are not evaluated while the vignette is built.

Installation

Install the released version from CRAN:

install.packages("sidrar")

Install the development version from GitHub with pak:

# install.packages("pak")
pak::pak("rpradosiqueira/sidrar")

Find and inspect a table

search_sidra() searches titles in IBGE's official aggregate catalog. Its result is a character vector whose names are the SIDRA table codes:

library(sidrar)

search_sidra("IPCA")
search_sidra(c("contas", "nacionais"))

The search is case- and accent-insensitive. When several terms are supplied, all terms must occur in the title, but they need not be adjacent.

Once you have a code, inspect the periods, variables, classifications, categories, and territorial levels accepted by the table:

metadata <- info_sidra(7060)
names(metadata)
metadata$variable
metadata$classific_category
metadata$geo

Set wb = TRUE to open the official table descriptor in the default browser. The function no longer prompts for confirmation:

info_sidra(7060, wb = TRUE)

Build a structured request

This request retrieves the monthly IPCA for the general index in Campo Grande, Mato Grosso do Sul, over the 12 most recent periods:

ipca <- get_sidra(
  x = 7060,
  variable = 63,
  period = c(last = 12),
  geo = "City",
  geo.filter = list(City = 5002704),
  classific = "c315",
  category = list(7169)
)

geo.filter may also select every unit inside a higher territorial level. For example, the following pattern requests cities inside Mato Grosso do Sul:

get_sidra(
  x = 7060,
  variable = 63,
  period = "last",
  geo = "City",
  geo.filter = list(State = 50),
  classific = "c315",
  category = list(7169)
)

The existing defaults remain unchanged: descriptive headers are enabled, format = 4 requests codes and names, digits = "default" uses the table's standard precision, and variable = "allxp" excludes automatically generated percentage variables.

Use an API path or full URL

If a query was assembled elsewhere, pass either its path:

get_sidra(
  api = "/t/7060/n1/all/v/63/p/last/c315/7169"
)

or the complete official HTTPS URL:

get_sidra(
  api = paste0(
    "https://apisidra.ibge.gov.br/values/",
    "t/7060/n1/all/v/63/p/last/c315/7169"
  )
)

Full URLs are restricted to the official https://apisidra.ibge.gov.br/values endpoint. Percent-encoded segments such as %20 are preserved. If the path contains /h/n, the first observation is kept as data instead of being interpreted as a header.

Preserve SIDRA's special values

SIDRA uses symbols with specific meanings, including "-" for an absolute zero, "X" for an inhibited value, ".." when a value does not apply, and "..." when it is unavailable. Earlier versions returned a numeric Valor column, so special symbols became NA. That remains the default for compatibility.

Use value_type = "character" to keep the symbols directly:

raw <- get_sidra(
  api = "/t/1849/n3/all/v/811/p/2018/c12762/all",
  value_type = "character"
)

Use value_type = "both" to keep numeric Valor and append Valor_raw:

both <- get_sidra(
  api = "/t/1849/n3/all/v/811/p/2018/c12762/all",
  value_type = "both"
)

Network behavior

Requests use HTTPS, UTF-8 decoding, an identifying user agent, a timeout, and limited retries for transient failures. Customize the timeout and retry count with:

options(
  sidrar.timeout = 120,
  sidrar.retries = 4
)

Invalid parameters and API limits are reported with the response returned by SIDRA. See the official API help for the complete query syntax and current service limits.