get_sidra: Get a SIDRA table

In sidrar: An Interface to IBGE's SIDRA API

Get a SIDRA table

Description

Retrieves aggregate data from the Brazilian Institute of Geography and Statistics (IBGE) SIDRA API.

Usage

get_sidra(
  x,
  variable = "allxp",
  period = "last",
  geo = "Brazil",
  geo.filter = NULL,
  classific = "all",
  category = "all",
  header = TRUE,
  format = 4,
  digits = "default",
  api = NULL,
  value_type = c("numeric", "character", "both"),
  geo_view = NULL,
  include_extinct = FALSE
)

Arguments

x	A numeric SIDRA table code. It may be omitted when api is used.
variable	A vector of variable codes. Defaults to "allxp", which selects all variables except automatically generated percentages.
period	A character vector of period codes, "all", or a single named value such as c(last = 12) or c(first = 5). Defaults to "last", the latest available period.
geo	A character vector containing supported geographic levels. Aliases and their nNN codes are case-insensitive. Defaults to "Brazil".
geo.filter	A list of geographic filters. Each element corresponds positionally to an element of geo; names may identify a higher geographic level, such as list(State = 50) for cities in a state.
classific	A vector of classification codes. Defaults to "all".
category	"all" or a list containing categories for each classification.
header	Logical. Should the first API record be used as the returned column names?
format	An integer from 1 to 4 controlling the returned descriptor fields. See Details.
digits	"default", "max", or an integer from 0 to 9.
api	A relative SIDRA API path or a complete URL under ⁠https://apisidra.ibge.gov.br/values⁠. When supplied, the other query arguments are ignored.
value_type	How the value column is returned: "numeric" preserves the historical numeric interface, "character" preserves SIDRA symbols, and "both" keeps the numeric column and appends a ⁠_raw⁠ column.
geo_view	Optional numeric SIDRA territorial-view code, using the API's G parameter instead of an N level. It cannot be combined with explicitly supplied geo or geo.filter values.
include_extinct	Logical. Include extinct territorial units in geo queries through the API's ⁠/u/y⁠ parameter. It cannot be combined with geo_view.

Details

Supported values of geo are "Brazil", "Region", "State", "IntermediaryRegion", "ImmediateRegion", "MesoRegion", "MicroRegion", "MetroRegion", "MetroRegionDiv", "IRD", "UrbAglo", "PopArrang", "City", "District", "subdistrict", and "Neighborhood". Their corresponding nNN codes and all aliases are accepted without regard to letter case.

format = 1 returns codes, format = 2 returns names, format = 3 returns codes and names for geographic units plus names for other descriptors, and format = 4 returns codes and names for all descriptors.

Requests use HTTPS, UTF-8 decoding, a timeout, and limited retries for transient failures. Set options(sidrar.timeout = 120) or options(sidrar.retries = 4) to override their defaults. Responses are requested live and are not cached by the package.

HTTP conditions inherit from sidrar_http_error and carry status_code, response_body, and url. Transport failures may additionally inherit from sidrar_timeout_error, sidrar_tls_error, sidrar_dns_error, sidrar_connection_error, or sidrar_transient_error when the underlying failure can be identified conservatively.

Cloudflare browser challenges raise sidrar_challenge_error, which inherits from sidrar_http_error and also carries cf_ray when available. For compatible values queries, the package retries through IBGE's official aggregate API v3 with view=flat. This fallback supports one geographic level, explicit or latest periods, standard variable/category selections, and the default format and precision. Unsupported selections retain the original challenge error with a fallback_reason field. Set options(sidrar.fallback = FALSE) to disable this alternative route. If the alternative request fails, its error carries primary_error with the original challenge. Availability still depends on IBGE; increasing retries does not solve a browser challenge. Automatic classification discovery (classific = "all") still requires access to SIDRA's table descriptor before requesting values.

When SIDRA rejects a query for exceeding its per-request value limit, get_sidra() raises a sidrar_limit_error, which also inherits from sidrar_http_error. The condition records requested_values, limit_values, and minimum_batches. Split an explicit dimension such as period, geo.filter, variable, or category across disjoint calls and combine the returned rows.

The SIDRA API uses special value symbols. With the default value_type = "numeric", non-numeric symbols such as "-", "X", "..", and "..." become NA, as in earlier versions. Use value_type = "character" or "both" when those distinctions matter.

Geographic identifiers returned by SIDRA should be kept as character strings. In particular, "Neighborhood" (n102) identifiers belong to SIDRA's territorial level and are not census tract identifiers; do not join them directly without an official correspondence.

Value

A base data.frame.

Author(s)

Renato Prado Siqueira [e-mail]

See Also

info_sidra(), search_sidra(), sidra_query(), and sidra_collect()

Examples

## Not run: 
get_sidra(
  x = 7060,
  variable = 63,
  period = c(last = 12),
  geo = "City",
  geo.filter = list(State = 50),
  classific = "c315",
  category = list(7169)
)

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

## End(Not run)

sidrar documentation built on Sept. 18, 2026, 9:14 a.m.