---
title: "Introduction to sidrar"
author: "Renato Prado Siqueira"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to sidrar}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>")
```

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

```{r, eval = FALSE}
install.packages("sidrar")
```

Install the development version from GitHub with `pak`:

```{r, eval = FALSE}
# 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:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
get_sidra(
  api = "/t/7060/n1/all/v/63/p/last/c315/7169"
)
```

or the complete official HTTPS URL:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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`:

```{r, eval = FALSE}
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:

```{r, eval = FALSE}
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](https://apisidra.ibge.gov.br/home/ajuda) for the complete
query syntax and current service limits.