Author: Renato Prado Siqueira

# Introduction to sidrar

#### Renato Prado Siqueira

## 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:

1. find a table with `search_sidra()`;
2. inspect its available dimensions with `info_sidra()`; and
3. 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.