The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

sidrar

sidrar provides direct access from R to aggregate data and metadata published by the Brazilian Institute of Geography and Statistics (IBGE). SIDRA stands for Sistema IBGE de Recuperação Automática.

Installation

Install the released version from CRAN:

install.packages("sidrar")

Install the development version from GitHub with:

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

Main functions

The original three entry points remain unchanged:

• search_sidra() searches the current official aggregate catalog.
• info_sidra() lists the parameters available for a table.
• get_sidra() retrieves the selected observations.

Table codes are returned as the names of the search_sidra() result:

search_sidra("IPCA")
info_sidra(7060)

An additive workflow is available for programmatic discovery, planning, and larger requests:

• sidra_catalog(), sidra_metadata(), sidra_periods(), and sidra_locations() return structured discovery data.
• sidra_query() constructs a request without downloading values, and sidra_plan() reports the cardinalities that can be determined offline.
• sidra_split() creates explicit disjoint batches and sidra_collect() retrieves them sequentially with schema validation.

Discover and plan

The structured discovery functions keep identifiers as character strings and return stable base R objects:

catalog <- sidra_catalog()
metadata <- sidra_metadata(7060)
periods <- sidra_periods(7060)
brazil <- sidra_locations(7060, "N1")

Build and inspect a query before downloading values:

query <- sidra_query(
  x = 7060,
  variable = 63,
  period = sprintf("2024%02d", 1:12),
  geo = "City",
  geo.filter = list(City = 5002704),
  classific = "c315",
  category = list(7169)
)

query$url
sidra_plan(query)

Retrieve data

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

library(sidrar)

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

You may also pass either a relative API path or a complete official HTTPS URL. A request containing /h/n is returned without consuming its first observation as a header:

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

Preserve special values

By default, Valor is numeric for compatibility with earlier releases. SIDRA also uses symbols such as "-", "X", "..", and "...". Use value_type = "character" to preserve them in Valor, or value_type = "both" to append Valor_raw while retaining numeric Valor:

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

Network behavior and cache

The legacy functions continue to query current IBGE services on every call. The structured discovery functions have an opt-in disk cache; value responses are never cached automatically:

metadata <- sidra_metadata(7060, cache = TRUE)
sidra_cache_info()
sidra_cache_clear()

Cache entries expire after 30 minutes by default. Use refresh = TRUE to bypass and replace an entry. Save collected values explicitly when a reproducible snapshot is required. Requests use a timeout and limited retries for transient failures; customize them with:

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

Regular package tests are offline. Live API smoke tests run separately on a small set of queries to detect availability and schema changes.

Requests above the SIDRA value limit

When SIDRA rejects a request because it exceeds the service’s per-request value limit, get_sidra() raises a sidrar_limit_error. Its message reports the requested count, the current limit, and the minimum number of calls. The condition also inherits from sidrar_http_error, so existing error handlers continue to work.

sidra_split() partitions one explicit dimension without splitting category sums or changing the geographic level. A geographic filter is splittable only when the query requests one non-Brazil level; otherwise unchanged territorial levels could overlap between calls. Relative periods, ranges, and embedded comma lists must first be expanded into one explicit code per vector element. sidra_collect() runs the resulting queries sequentially and refuses to combine incompatible schemas:

query <- sidra_query(
  x = table_code,
  variable = variable_code,
  period = period_code,
  geo = "City",
  classific = classification_code,
  category = list(category_codes)
)

batches <- sidra_split(query, by = "category", size = 8)
data <- sidra_collect(batches, provenance = TRUE)
sidra_provenance(data)

The appropriate group size depends on the cardinality of every selected dimension. Automatic implicit splitting remains disabled.

Geographic identifiers

Keep geographic identifiers as character strings. SIDRA neighborhood codes (geo = "Neighborhood") identify its neighborhood territorial level; they are not census tract identifiers and must not be joined directly to census tract geometries without an official correspondence.

Structured queries also support official territorial views and extinct territorial units:

sidra_query(1612, geo_view = 44, classific = character())
sidra_query(
  1612,
  geo = "State",
  geo.filter = list(c(20, 34)),
  include_extinct = TRUE,
  classific = character()
)

For more examples, see the “Introduction to sidrar” vignette and the official SIDRA API documentation.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.