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.

Cloudflare access challenges

Some SIDRA values requests have returned a Cloudflare browser challenge (HTTP 403, Just a moment...) since reports dated September 15, 2026. This is an access restriction upstream, rather than a malformed query.

Version 0.5.1 recognizes this response and, for compatible queries, uses the official IBGE aggregate API v3 with view=flat. Existing calls to get_sidra() and sidra_collect() can use this fallback without changing their arguments. It supports one geographic level (including a containing level filter), explicit periods or last, explicit variable/category codes or all/allxp as appropriate, and the default format and precision. Header handling and value_type remain unchanged. A message identifies when the alternative endpoint is used.

When classific = "all" discovers classifications automatically, SIDRA’s descriptor endpoint must also be accessible before values can be requested.

Territorial views, extinct-unit options, multiple geographic levels, first or all periods, ranges, category sums, custom format/precision, and other unsupported URL options are not translated automatically. The original sidrar_challenge_error then explains the limitation in fallback_reason. For URLs supplied through api, dimensions must follow the standard geography, period, variable, classification order used by sidra_query(), with period and variable specified explicitly. You can disable fallback with options(sidrar.fallback = FALSE).

If both official endpoints are unavailable, the package cannot restore access itself. Report the failing URL, access time, and cf_ray from the condition to IBGE. Increasing retries does not solve browser challenges. With sidra_collect(..., provenance = TRUE), urls records the actual endpoints and requested_urls records the original queries when fallback occurs.

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.