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 429 and 503 responses honor a valid Retry-After delay (seconds or HTTP date). Set options(sidrar.retry_after_max = 120) to change the maximum server-requested delay accepted for another attempt (default: 60 seconds). The option must be one finite positive number; invalid settings use 60. If the requested delay exceeds that limit, a sidrar_retry_after_error (also a sidrar_http_error) carries retry_after and retry_after_max, rather than retrying before the server permits it. This limit does not change the per-attempt timeout or the total number of attempts.

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 multiple geographic levels, explicit periods and ranges, all, first, and last selections, standard variable/category selections, and the default descriptor format. Dimension columns follow the original URL, including when variable precedes period; observation order remains that returned by the alternative service. Explicit decimal precision is accepted only when numeric values already have the requested decimal places. Otherwise sidrar_fallback_precision_error (also a sidrar_parse_error) is raised: the alternative cannot reconstruct unavailable precision, and values are not rounded or padded. The default precision preserves values as received; maximum precision is unsupported. 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") can use official aggregate metadata if SIDRA's table descriptor returns a browser challenge.

Alternative responses are checked for complete dimension fields, textual identifiers, duplicate observation keys, and membership in explicit filters. Violations raise sidrar_parse_error subclasses and retain primary_error. Missing explicitly selected members produce sidrar_incomplete_warning, whose missing field identifies them, without adding or removing rows. This warning does not prove truncation: sparse tables can legitimately omit observations. No Cartesian product is required. Full coverage of all, the exact membership of first/latest selections, and containing-level geographic filters require catalog or territorial metadata comparisons and are not inferred by these local checks.

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. Use sidra_split() to split a URL or structured query across disjoint calls, or sidra_collect() with batch_size for opt-in period batching and checkpoint for resumable downloads. get_sidra() itself does not split requests or save values.

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. 28, 2026, 5:07 p.m.