--- title: "Getting started with ibger" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting started with ibger} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ## Overview **ibger** provides a tidyverse-friendly interface to the [IBGE Aggregate Data API](https://servicodados.ibge.gov.br/api/docs/agregados?versao=3) (version 3). This is the same API that powers [SIDRA](https://sidra.ibge.gov.br/) — the automatic data retrieval system for all surveys and censuses conducted by the Brazilian Institute of Geography and Statistics (IBGE). Each SIDRA table corresponds to an **aggregate** in the API. With ibger you can browse aggregates, inspect their metadata, and retrieve tidy data — all from R. All the output shown in this vignette was produced by running the code against the live API when the vignette was last built (see the date at the end); numbers such as the catalog size or the latest period will change over time. ## Installation ``` r # CRAN release install.packages("ibger") # Development version # install.packages("remotes") remotes::install_github("ropensci/ibger") ``` ``` r library(ibger) ``` ## A typical workflow ### Step 1 — Find an aggregate Use `ibge_aggregates()` to list every aggregate grouped by survey. Optional filters let you narrow the search. Subject codes come from `ibge_subjects()`; `70` is "Abate de animais" (animal slaughter): ``` r # All aggregates (the catalog is large: only the first rows are shown) ibge_aggregates() #> ℹ Fetching aggregates from IBGE API... #> ✔ Fetching aggregates from IBGE API... [755ms] #> #> ✔ 9336 aggregates found. #> # A tibble: 9,336 × 4 #> survey_id survey_name aggregate_id aggregate_name #> #> 1 D5 "Áreas Urbanizadas do Brasil" 10763 Áreas urbaniz… #> 2 D5 "Áreas Urbanizadas do Brasil" 8418 Áreas urbaniz… #> 3 EO "Avaliação dos dados sobre a Biodivers… 10510 Índice de con… #> 4 EO "Avaliação dos dados sobre a Biodivers… 10511 Quantidade de… #> 5 EO "Avaliação dos dados sobre a Biodivers… 10512 Categorias de… #> 6 CL "Cadastro Central de Empresas" 1685 Unidades loca… #> 7 CL "Cadastro Central de Empresas" 1732 Dados gerais … #> 8 CL "Cadastro Central de Empresas" 1733 Dados gerais … #> 9 CL "Cadastro Central de Empresas" 1734 Dados gerais … #> 10 CL "Cadastro Central de Empresas" 1735 Dados gerais … #> # ℹ 9,326 more rows # One subject: animal slaughter ibge_aggregates(subject = 70) #> ℹ Fetching aggregates from IBGE API... #> ✔ Fetching aggregates from IBGE API... [155ms] #> #> ✔ 16 aggregates found. #> # A tibble: 16 × 4 #> survey_id survey_name aggregate_id aggregate_name #> #> 1 AB Pesquisa Mensal de Abate de Animais 19 Quantidade de… #> 2 AB Pesquisa Mensal de Abate de Animais 20 Peso das carc… #> 3 AB Pesquisa Mensal de Abate de Animais 41 Quantidade de… #> 4 AB Pesquisa Mensal de Abate de Animais 42 Quantidade de… #> 5 AB Pesquisa Mensal de Abate de Animais 43 Quantidade de… #> 6 AB Pesquisa Mensal de Abate de Animais 44 Quantidade de… #> 7 AB Pesquisa Mensal de Abate de Animais 45 Peso das carc… #> 8 AB Pesquisa Mensal de Abate de Animais 46 Peso das carc… #> 9 AB Pesquisa Mensal de Abate de Animais 47 Peso das carc… #> 10 AB Pesquisa Mensal de Abate de Animais 48 Peso das carc… #> 11 AX Pesquisa Trimestral do Abate de Animais 1092 Número de inf… #> 12 AX Pesquisa Trimestral do Abate de Animais 1093 Número de inf… #> 13 AX Pesquisa Trimestral do Abate de Animais 1094 Número de inf… #> 14 AX Pesquisa Trimestral do Abate de Animais 6669 Quantidade e … #> 15 AX Pesquisa Trimestral do Abate de Animais 6829 Quantidade e … #> 16 AX Pesquisa Trimestral do Abate de Animais 9395 Número de inf… # Monthly aggregates only ibge_aggregates(periodicity = "P5") #> ℹ Fetching aggregates from IBGE API... #> ✔ Fetching aggregates from IBGE API... [75ms] #> #> ✔ 288 aggregates found. #> # A tibble: 288 × 4 #> survey_id survey_name aggregate_id aggregate_name #> #> 1 IL Índice de Preços ao Consumidor em Real 86 IPCR - Percent… #> 2 IL Índice de Preços ao Consumidor em Real 89 IPCR - Peso no… #> 3 IR Índice de Preços ao Produtor 3104 Índice de Preç… #> 4 IR Índice de Preços ao Produtor 5796 Índice de Preç… #> 5 IR Índice de Preços ao Produtor 5800 Índice de Preç… #> 6 IR Índice de Preços ao Produtor 6723 Índice de Preç… #> 7 IR Índice de Preços ao Produtor 6903 Índice de Preç… #> 8 IR Índice de Preços ao Produtor 6904 Índice de Preç… #> 9 IJ Índice de Reajuste do Salário Mínimo 90 IRSM - Percent… #> 10 IJ Índice de Reajuste do Salário Mínimo 91 IRSM - Peso no… #> # ℹ 278 more rows # Aggregates with municipality-level data ibge_aggregates(level = "N6") #> ℹ Fetching aggregates from IBGE API... #> ✔ Fetching aggregates from IBGE API... [1.2s] #> #> ✔ 4448 aggregates found. #> # A tibble: 4,448 × 4 #> survey_id survey_name aggregate_id aggregate_name #> #> 1 D5 "Áreas Urbanizadas do Brasil" 10763 Áreas urbaniz… #> 2 D5 "Áreas Urbanizadas do Brasil" 8418 Áreas urbaniz… #> 3 EO "Avaliação dos dados sobre a Biodivers… 10510 Índice de con… #> 4 EO "Avaliação dos dados sobre a Biodivers… 10511 Quantidade de… #> 5 EO "Avaliação dos dados sobre a Biodivers… 10512 Categorias de… #> 6 CL "Cadastro Central de Empresas" 1685 Unidades loca… #> 7 CL "Cadastro Central de Empresas" 1734 Dados gerais … #> 8 CL "Cadastro Central de Empresas" 1735 Dados gerais … #> 9 CL "Cadastro Central de Empresas" 2933 Empresas e ou… #> 10 CL "Cadastro Central de Empresas" 3421 Unidades loca… #> # ℹ 4,438 more rows ``` The filters are checked before the request: the API silently ignores values it cannot parse, so a typo would otherwise return the whole catalog. ``` r ibge_aggregates(periodicity = "monthly") #> Error: #> ! Invalid `periodicity` filter: "monthly". #> ℹ Expected a single value like "P5". #> ℹ See `?ibge_aggregates` for the accepted formats. ``` ### Step 2 — Inspect the metadata Once you have an aggregate ID, `ibge_metadata()` tells you everything about its structure. Aggregate **1092** is the quarterly animal slaughter table (number of establishments, animals slaughtered and carcass weight): ``` r meta <- ibge_metadata(1092) #> ℹ Fetching metadata for aggregate 1092 from IBGE API... #> ✔ Fetching metadata for aggregate 1092 from IBGE API... [161ms] #> #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories. meta #> #> ── Número de informantes, Quantidade e Peso total das carcaças dos bovinos abati #> ID: 1092 #> Survey: Pesquisa Trimestral do Abate de Animais #> Subject: Abate de animais #> Periodicity: trimestral (199701 to 202602) #> Territorial levels: N1, N3 #> #> ── Variables (6) ── #> #> 151: Número de informantes (Unidades) #> 1000151: Número de informantes - percentual do total geral (%) #> 284: Animais abatidos (Cabeças) #> 1000284: Animais abatidos - percentual do total geral (%) #> 285: Peso total das carcaças (Quilogramas) #> 1000285: Peso total das carcaças - percentual do total geral (%) #> #> ── Classifications (3) ── #> #> 12716: Referência temporal (4 categories) #> 115236: Total do trimestre [level 0] #> 115233: No 1º mês [level 1] #> 115234: No 2º mês [level 1] #> 115235: No 3º mês [level 1] #> 18: Tipo de rebanho bovino (6 categories) #> 992: Total [level 0] #> 55: Bois [level 1] #> 56: Vacas [level 1] #> 111734: Novilhos [level 1] #> 111735: Novilhas [level 1] #> ... and 1 more categories #> 12529: Tipo de inspeção (4 categories) #> 118225: Total [level 0] #> 111737: Federal [level 1] #> 111738: Estadual [level 1] #> 111739: Municipal [level 1] #> #> Use `meta$variables` and `meta$classifications` to access the data. #> Use `tidyr::unnest(meta$classifications, categories)` to unnest. ``` Each component is accessible directly: ``` r meta$variables #> # A tibble: 6 × 3 #> id name unit #> #> 1 151 Número de informantes Unidades #> 2 1000151 Número de informantes - percentual do total geral % #> 3 284 Animais abatidos Cabeças #> 4 1000284 Animais abatidos - percentual do total geral % #> 5 285 Peso total das carcaças Quilogramas #> 6 1000285 Peso total das carcaças - percentual do total geral % meta$classifications #> # A tibble: 3 × 3 #> id name categories #> #> 1 12716 Referência temporal #> 2 18 Tipo de rebanho bovino #> 3 12529 Tipo de inspeção # Unnest to see every category tidyr::unnest(meta$classifications, categories) #> # A tibble: 14 × 6 #> id name category_id category_name category_unit category_level #> #> 1 12716 Referência temp… 115236 Total do tri… 0 #> 2 12716 Referência temp… 115233 No 1º mês 1 #> 3 12716 Referência temp… 115234 No 2º mês 1 #> 4 12716 Referência temp… 115235 No 3º mês 1 #> 5 18 Tipo de rebanho… 992 Total 0 #> 6 18 Tipo de rebanho… 55 Bois 1 #> 7 18 Tipo de rebanho… 56 Vacas 1 #> 8 18 Tipo de rebanho… 111734 Novilhos 1 #> 9 18 Tipo de rebanho… 111735 Novilhas 1 #> 10 18 Tipo de rebanho… 57 Vitelos e vi… 1 #> 11 12529 Tipo de inspeção 118225 Total 0 #> 12 12529 Tipo de inspeção 111737 Federal 1 #> 13 12529 Tipo de inspeção 111738 Estadual 1 #> 14 12529 Tipo de inspeção 111739 Municipal 1 # Geographic levels meta$territorial_level #> $administrative #> [1] "N1" "N3" #> #> $special #> character(0) #> #> $ibge #> character(0) # Time range meta$periodicity #> $frequency #> [1] "trimestral" #> #> $start #> [1] 199701 #> #> $end #> [1] 202602 ``` ### Step 3 — Retrieve data `ibge_variables()` is the main workhorse. It sends the request and returns a tidy tibble (one row per variable × locality × period × category): ``` r ibge_variables(1092, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [73ms] #> #> ✔ 18 records retrieved. #> # A tibble: 18 × 11 #> variable_id variable_name variable_unit classification_18 #> #> 1 151 Número de informantes Unidades Total #> 2 151 Número de informantes Unidades Total #> 3 151 Número de informantes Unidades Total #> 4 151 Número de informantes Unidades Total #> 5 151 Número de informantes Unidades Total #> 6 151 Número de informantes Unidades Total #> 7 284 Animais abatidos Cabeças Total #> 8 284 Animais abatidos Cabeças Total #> 9 284 Animais abatidos Cabeças Total #> 10 284 Animais abatidos Cabeças Total #> 11 284 Animais abatidos Cabeças Total #> 12 284 Animais abatidos Cabeças Total #> 13 285 Peso total das carcaças Quilogramas Total #> 14 285 Peso total das carcaças Quilogramas Total #> 15 285 Peso total das carcaças Quilogramas Total #> 16 285 Peso total das carcaças Quilogramas Total #> 17 285 Peso total das carcaças Quilogramas Total #> 18 285 Peso total das carcaças Quilogramas Total #> # ℹ 7 more variables: classification_12529 , classification_12716 , #> # locality_id , locality_name , locality_level , period , #> # value ``` ## Specifying localities The `localities` parameter accepts several convenient formats: ``` r # Country total ibge_variables(1092, variable = 284, periods = -1, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [74ms] #> #> ✔ 1 record retrieved. #> # A tibble: 1 × 11 #> variable_id variable_name variable_unit classification_18 classification_12529 #> #> 1 284 Animais abat… Cabeças Total Total #> # ℹ 6 more variables: classification_12716 , locality_id , #> # locality_name , locality_level , period , value # All states ibge_variables(1092, variable = 284, periods = -1, localities = "N3") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching N3 localities for aggregate 1092 from IBGE API... #> ✔ Fetching N3 localities for aggregate 1092 from IBGE API... [142ms] #> #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [69ms] #> #> ✔ 27 records retrieved. #> # A tibble: 27 × 11 #> variable_id variable_name variable_unit classification_18 #> #> 1 284 Animais abatidos Cabeças Total #> 2 284 Animais abatidos Cabeças Total #> 3 284 Animais abatidos Cabeças Total #> 4 284 Animais abatidos Cabeças Total #> 5 284 Animais abatidos Cabeças Total #> 6 284 Animais abatidos Cabeças Total #> 7 284 Animais abatidos Cabeças Total #> 8 284 Animais abatidos Cabeças Total #> 9 284 Animais abatidos Cabeças Total #> 10 284 Animais abatidos Cabeças Total #> # ℹ 17 more rows #> # ℹ 7 more variables: classification_12529 , classification_12716 , #> # locality_id , locality_name , locality_level , period , #> # value # Specific states (RJ = 33, SP = 35) ibge_variables(1092, variable = 284, periods = -1, localities = list(N3 = c(33, 35))) #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [69ms] #> #> ✔ 2 records retrieved. #> # A tibble: 2 × 11 #> variable_id variable_name variable_unit classification_18 classification_12529 #> #> 1 284 Animais abat… Cabeças Total Total #> 2 284 Animais abat… Cabeças Total Total #> # ℹ 6 more variables: classification_12716 , locality_id , #> # locality_name , locality_level , period , value # Mix levels: two metropolitan areas + one municipality # (IPCA, aggregate 7060, is published for metropolitan areas and capitals) ibge_variables(7060, variable = 63, periods = -1, localities = list(N7 = c(3501, 3301), N6 = 5208707)) #> ℹ Fetching metadata for aggregate 7060 from IBGE API... #> ✔ Fetching metadata for aggregate 7060 from IBGE API... [74ms] #> #> ✔ Aggregate 7060: 4 variables, #> 1 classification, 457 categories. #> ℹ Fetching variables for aggregate 7060 from IBGE API... #> ✔ Fetching variables for aggregate 7060 from IBGE API... [123ms] #> #> ✔ 3 records retrieved. #> # A tibble: 3 × 9 #> variable_id variable_name variable_unit classification_315 locality_id #> #> 1 63 IPCA - Variação mens… % Índice geral 3501 #> 2 63 IPCA - Variação mens… % Índice geral 3301 #> 3 63 IPCA - Variação mens… % Índice geral 5208707 #> # ℹ 4 more variables: locality_name , locality_level , period , #> # value ``` The geographic level codes follow the IBGE convention: | Code | Level | Example | |------|----------------------------|--------------------------------------| | `N1` | Brazil | `"BR"` or `list(N1 = 1)` | | `N2` | Major region | `list(N2 = 1)` — North | | `N3` | State (UF) | `list(N3 = 33)` — Rio de Janeiro | | `N6` | Municipality | `list(N6 = 3550308)` — São Paulo/SP | | `N7` | Metropolitan area | `list(N7 = 3501)` — RM São Paulo | > **Tip**: Not every aggregate is available at every level. Aggregate 1092 > has data for N1 and N3 but not N6. Use `ibge_metadata()` to check, or > rely on the validation described below. ## Specifying periods Periods follow the API convention — negative values mean "last N": ``` r # Last 6 periods (the default) ibge_variables(1092, variable = 284, periods = -6, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [70ms] #> #> ✔ 6 records retrieved. #> # A tibble: 6 × 11 #> variable_id variable_name variable_unit classification_18 classification_12529 #> #> 1 284 Animais abat… Cabeças Total Total #> 2 284 Animais abat… Cabeças Total Total #> 3 284 Animais abat… Cabeças Total Total #> 4 284 Animais abat… Cabeças Total Total #> 5 284 Animais abat… Cabeças Total Total #> 6 284 Animais abat… Cabeças Total Total #> # ℹ 6 more variables: classification_12716 , locality_id , #> # locality_name , locality_level , period , value # Last 12 periods ibge_variables(1092, variable = 284, periods = -12, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [80ms] #> #> ✔ 12 records retrieved. #> # A tibble: 12 × 11 #> variable_id variable_name variable_unit classification_18 #> #> 1 284 Animais abatidos Cabeças Total #> 2 284 Animais abatidos Cabeças Total #> 3 284 Animais abatidos Cabeças Total #> 4 284 Animais abatidos Cabeças Total #> 5 284 Animais abatidos Cabeças Total #> 6 284 Animais abatidos Cabeças Total #> 7 284 Animais abatidos Cabeças Total #> 8 284 Animais abatidos Cabeças Total #> 9 284 Animais abatidos Cabeças Total #> 10 284 Animais abatidos Cabeças Total #> 11 284 Animais abatidos Cabeças Total #> 12 284 Animais abatidos Cabeças Total #> # ℹ 7 more variables: classification_12529 , classification_12716 , #> # locality_id , locality_name , locality_level , period , #> # value # Specific period codes (IPCA is monthly: 202301 = January 2023) ibge_variables(7060, variable = 63, periods = c(202301, 202302, 202303), localities = "BR") #> ✔ Aggregate 7060: 4 variables, #> 1 classification, 457 categories (cached). #> ℹ Fetching variables for aggregate 7060 from IBGE API... #> ✔ Fetching variables for aggregate 7060 from IBGE API... [72ms] #> #> ✔ 3 records retrieved. #> # A tibble: 3 × 9 #> variable_id variable_name variable_unit classification_315 locality_id #> #> 1 63 IPCA - Variação mens… % Índice geral 1 #> 2 63 IPCA - Variação mens… % Índice geral 1 #> 3 63 IPCA - Variação mens… % Índice geral 1 #> # ℹ 4 more variables: locality_name , locality_level , period , #> # value # Range (inclusive) ibge_variables(7060, variable = 63, periods = "202101-202104", localities = "BR") #> ✔ Aggregate 7060: 4 variables, #> 1 classification, 457 categories (cached). #> ℹ Fetching variables for aggregate 7060 from IBGE API... #> ✔ Fetching variables for aggregate 7060 from IBGE API... [159ms] #> #> ✔ 4 records retrieved. #> # A tibble: 4 × 9 #> variable_id variable_name variable_unit classification_315 locality_id #> #> 1 63 IPCA - Variação mens… % Índice geral 1 #> 2 63 IPCA - Variação mens… % Índice geral 1 #> 3 63 IPCA - Variação mens… % Índice geral 1 #> 4 63 IPCA - Variação mens… % Índice geral 1 #> # ℹ 4 more variables: locality_name , locality_level , period , #> # value # Range + extra period ibge_variables(7060, variable = 63, periods = "202101-202103|202301", localities = "BR") #> ✔ Aggregate 7060: 4 variables, #> 1 classification, 457 categories (cached). #> ℹ Fetching variables for aggregate 7060 from IBGE API... #> ✔ Fetching variables for aggregate 7060 from IBGE API... [76ms] #> #> ✔ 4 records retrieved. #> # A tibble: 4 × 9 #> variable_id variable_name variable_unit classification_315 locality_id #> #> 1 63 IPCA - Variação mens… % Índice geral 1 #> 2 63 IPCA - Variação mens… % Índice geral 1 #> 3 63 IPCA - Variação mens… % Índice geral 1 #> 4 63 IPCA - Variação mens… % Índice geral 1 #> # ℹ 4 more variables: locality_name , locality_level , period , #> # value ``` > **Note**: Negative values cannot be mixed with specific periods. Period > codes encode both the date and the periodicity — `202001` means > January 2020 in a monthly aggregate but the first quarter of 2020 in a > quarterly one. `ibge_metadata()` reports the periodicity, and > `ibge_periods()` lists the valid codes. ## Filtering with classifications Many aggregates break their data further by classifications (dimensions). For instance, aggregate 1712 (temporary crops in the 2006 Agricultural Census) has a classification for the product (226) and another for the producer's condition (218). ``` r # Single category: pineapple (4844) from product classification (226) ibge_variables( aggregate = 1712, variable = 214, localities = "BR", classification = list("226" = 4844) ) #> ℹ Fetching metadata for aggregate 1712 from IBGE API... #> ✔ Fetching metadata for aggregate 1712 from IBGE API... [71ms] #> #> ✔ Aggregate 1712: 7 variables, #> 6 classifications, 108 categories. #> ℹ Fetching variables for aggregate 1712 from IBGE API... #> ✔ Fetching variables for aggregate 1712 from IBGE API... [73ms] #> #> ✔ 1 record retrieved. #> # A tibble: 1 × 14 #> variable_id variable_name variable_unit classification_226 classification_218 #> #> 1 214 Quantidade pr… Mil frutos Abacaxi Total #> # ℹ 9 more variables: classification_220 , classification_12517 , #> # classification_12523 , classification_12617 , locality_id , #> # locality_name , locality_level , period , value # Multiple categories ibge_variables( aggregate = 1712, variable = 214, localities = "BR", classification = list("226" = c(4844, 96608, 96609)) ) #> ✔ Aggregate 1712: 7 variables, #> 6 classifications, 108 categories (cached). #> ℹ Fetching variables for aggregate 1712 from IBGE API... #> ✔ Fetching variables for aggregate 1712 from IBGE API... [76ms] #> #> ✔ 3 records retrieved. #> # A tibble: 3 × 14 #> variable_id variable_name variable_unit classification_226 classification_218 #> #> 1 214 Quantidade pr… Mil frutos Abacaxi Total #> 2 214 Quantidade pr… Mil frutos Amendoim em casca Total #> 3 214 Quantidade pr… Mil frutos Batata-inglesa Total #> # ℹ 9 more variables: classification_220 , classification_12517 , #> # classification_12523 , classification_12617 , locality_id , #> # locality_name , locality_level , period , value # Multiple classifications ibge_variables( aggregate = 1712, variable = 214, localities = "BR", classification = list("226" = c(4844, 96608), "218" = 4780) ) #> ✔ Aggregate 1712: 7 variables, #> 6 classifications, 108 categories (cached). #> ℹ Fetching variables for aggregate 1712 from IBGE API... #> ✔ Fetching variables for aggregate 1712 from IBGE API... [108ms] #> #> ✔ 2 records retrieved. #> # A tibble: 2 × 14 #> variable_id variable_name variable_unit classification_226 classification_218 #> #> 1 214 Quantidade pr… Mil frutos Abacaxi Proprietário #> 2 214 Quantidade pr… Mil frutos Amendoim em casca Proprietário #> # ℹ 9 more variables: classification_220 , classification_12517 , #> # classification_12523 , classification_12617 , locality_id , #> # locality_name , locality_level , period , value # All categories of a classification ibge_variables( aggregate = 1712, variable = 214, localities = "BR", classification = list("226" = "all") ) #> ✔ Aggregate 1712: 7 variables, #> 6 classifications, 108 categories (cached). #> ℹ Fetching variables for aggregate 1712 from IBGE API... #> ✔ Fetching variables for aggregate 1712 from IBGE API... [77ms] #> #> ✔ 53 records retrieved. #> # A tibble: 53 × 14 #> variable_id variable_name variable_unit classification_226 classification_218 #> #> 1 214 Quantidade p… Unidades Total Total #> 2 214 Quantidade p… Unidades Abacaxi Total #> 3 214 Quantidade p… Unidades Abóbora, moranga,… Total #> 4 214 Quantidade p… Unidades Algodão herbáceo Total #> 5 214 Quantidade p… Unidades Alho Total #> 6 214 Quantidade p… Unidades Amendoim em casca Total #> 7 214 Quantidade p… Unidades Arroz em casca Total #> 8 214 Quantidade p… Unidades Aveia branca em g… Total #> 9 214 Quantidade p… Unidades Batata-inglesa Total #> 10 214 Quantidade p… Unidades Cana-de-açúcar Total #> # ℹ 43 more rows #> # ℹ 9 more variables: classification_220 , classification_12517 , #> # classification_12523 , classification_12617 , locality_id , #> # locality_name , locality_level , period , value ``` When no classification is specified, the API returns the **Total** category (ID = 0) — an aggregate across all categories. ## Automatic validation Before sending any request, `ibge_variables()` and `ibge_localities()` validate your parameters against the aggregate's metadata. If something doesn't match, you get a clear error with the allowed values: ``` r # N6 (municipalities) is not available for aggregate 1092 ibge_variables(1092, localities = "N6") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> Error: #> ! Geographic level(s) "N6" not available for aggregate 1092. #> ℹ Available levels: "N1" and "N3". # Period out of range ibge_variables(1092, periods = 199001, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> Error: #> ! Period(s) 199001 out of range for aggregate 1092. #> ℹ Valid range: 199701 to 202602 (trimestral). # Non-existent variable ibge_variables(1092, variable = 999, localities = "BR") #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> Error: #> ! Variable(s) "999" not found in aggregate 1092. #> ℹ Available variables: #> 151 - Número de informantes (Unidades) #> 1000151 - Número de informantes - percentual do total geral (%) #> 284 - Animais abatidos (Cabeças) #> 1000284 - Animais abatidos - percentual do total geral (%) #> 285 - Peso total das carcaças (Quilogramas) #> 1000285 - Peso total das carcaças - percentual do total geral (%) # Non-existent category ibge_variables(1092, localities = "BR", classification = list("18" = 1)) #> ✔ Aggregate 1092: 6 variables, #> 3 classifications, 14 categories (cached). #> Error: #> ! Category(ies) "1" not found in classification "18" (Tipo de rebanho #> bovino). #> ℹ First categories available (6 total): #> 992 - Total #> 55 - Bois #> 56 - Vacas #> 111734 - Novilhos #> 111735 - Novilhas #> 57 - Vitelos e vitelas ``` Metadata is fetched once per session and cached. To force a refresh: ``` r ibge_clear_cache() #> ✔ Metadata cache cleared. ``` Skip validation entirely with `validate = FALSE`: ``` r ibge_variables(1092, variable = 284, periods = -1, localities = "BR", validate = FALSE) #> ℹ Fetching variables for aggregate 1092 from IBGE API... #> ✔ Fetching variables for aggregate 1092 from IBGE API... [75ms] #> #> ✔ 1 record retrieved. #> # A tibble: 1 × 11 #> variable_id variable_name variable_unit classification_18 classification_12529 #> #> 1 284 Animais abat… Cabeças Total Total #> # ℹ 6 more variables: classification_12716 , locality_id , #> # locality_name , locality_level , period , value ``` ## Large queries The API rejects requests whose result is too large (see `?ibge_variables` and the API-concepts vignette). You do not need to split such queries by hand: `ibge_variables()` estimates the result size from the metadata and, when it exceeds the limit, splits the request into several smaller ones and combines the results. The query below asks for the estimated population of every municipality (aggregate 6579, about 5,570 localities) for the last 12 years — some 67,000 values — and is transparently sent as two requests: ``` r pop <- ibge_variables(6579, localities = "N6", periods = -12) #> ℹ Fetching metadata for aggregate 6579 from IBGE API... #> ✔ Fetching metadata for aggregate 6579 from IBGE API... [70ms] #> #> ✔ Aggregate 6579: 1 variable, #> 0 classifications, 0 categories. #> ℹ Fetching N6 localities for aggregate 6579 from IBGE API... #> ✔ Fetching N6 localities for aggregate 6579 from IBGE API... [166ms] #> #> ℹ Fetching period list for aggregate 6579 from IBGE API... #> ✔ Fetching period list for aggregate 6579 from IBGE API... [71ms] #> #> ℹ Estimated result exceeds the API limit (50000 values); #> splitting into 2 requests. #> ℹ Fetching chunk 1/2 for aggregate 6579 from IBGE API... #> ✔ Fetching chunk 1/2 for aggregate 6579 from IBGE API... [186ms] #> #> ℹ Fetching chunk 2/2 for aggregate 6579 from IBGE API... #> ✔ Fetching chunk 2/2 for aggregate 6579 from IBGE API... [375ms] #> #> ✔ 66852 records retrieved. pop #> # A tibble: 66,852 × 8 #> variable_id variable_name variable_unit locality_id locality_name #> #> 1 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 2 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 3 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 4 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 5 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 6 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 7 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 8 9324 População residente esti… Pessoas 1100015 Alta Florest… #> 9 9324 População residente esti… Pessoas 1100023 Ariquemes - … #> 10 9324 População residente esti… Pessoas 1100023 Ariquemes - … #> # ℹ 66,842 more rows #> # ℹ 3 more variables: locality_level , period , value ``` Municipality-level requests are slow on the server side (one to several minutes each), so expect this to take a while. Use `chunk = FALSE` to force a single request, or pass a number to change the per-request limit. ## Browsing the survey catalog Beyond aggregate-level data, ibger also provides access to the [IBGE Metadata API](https://servicodados.ibge.gov.br/api/docs/metadados?versao=2) (v2), which catalogs IBGE's surveys with institutional and methodological information such as status, category, collection frequency, and thematic classifications. This is useful when you want to understand **what surveys exist** and **how they are structured** before diving into specific aggregates. ``` r # List all IBGE surveys ibge_surveys() #> ℹ Fetching survey catalog from IBGE Metadata API... #> ✔ Fetching survey catalog from IBGE Metadata API... [83ms] #> #> ✔ 100 surveys found. #> # A tibble: 100 × 8 #> id name name_en status category collection_frequency #> #> 1 AC "Pesquisa Anual da Indúst… Ativa Estrutu… Anual #> 2 AA "Pesquisa Nacional de Saú… Ativa Especial Eventual #> 3 AM "Pesquisa de Assistência … Desat… Especial Eventual #> 4 AX "Pesquisa Trimestral do A… Quarte… Ativa Conjunt… Trimestral #> 5 CD "Censo Demográfico" Popula… Ativa Estrutu… Decenal #> 6 CL "Cadastro Central de Empr… Busine… Ativa Estrutu… Anual #> 7 EI "Economia Informal Urbana" Urban … Concl… Outro Eventual #> 8 ER "Pesquisa das Característ… Ethno-… Desat… Especial Eventual #> 9 FP "Fundações Privadas e Ass… Ativa Outro Eventual #> 10 IA "Índice Nacional de Preço… Ativa Conjunt… Mensal #> # ℹ 90 more rows #> # ℹ 2 more variables: publication_frequency , #> # thematic_classifications # Filter active short-term ("conjuntural") surveys library(dplyr) #> #> Anexando pacote: 'dplyr' #> Os seguintes objetos são mascarados por 'package:stats': #> #> filter, lag #> Os seguintes objetos são mascarados por 'package:base': #> #> intersect, setdiff, setequal, union ibge_surveys(thematic_classifications = FALSE) |> filter(status == "Ativa", category == "Conjuntural") #> ℹ Fetching survey catalog from IBGE Metadata API... #> ✔ Fetching survey catalog from IBGE Metadata API... [154ms] #> #> ✔ 100 surveys found. #> # A tibble: 17 × 7 #> id name name_en status category collection_frequency #> #> 1 AX Pesquisa Trimestral do Ab… Quarte… Ativa Conjunt… Trimestral #> 2 IA Índice Nacional de Preços… Ativa Conjunt… Mensal #> 3 ST Contas Nacionais Trimestr… Ativa Conjunt… Trimestral #> 4 IR Índice de Preços ao Produ… Ativa Conjunt… Mensal #> 5 LT Pesquisa Trimestral do Le… Quarte… Ativa Conjunt… Trimestral #> 6 MC Pesquisa Mensal de Comérc… Monthl… Ativa Conjunt… Mensal #> 7 PC Índice Nacional de Preços… Ativa Conjunt… Mensal #> 8 PO Produção de Ovos de Galin… Quarte… Ativa Conjunt… Trimestral #> 9 SC Pesquisa Mensal de Serviç… Ativa Conjunt… Mensal #> 10 DD Pesquisa Nacional por Amo… Ativa Conjunt… Trimestral #> 11 ES Pesquisa de Estoques Survey… Ativa Conjunt… Semestral #> 12 BB Pesquisa Nacional por Amo… Ativa Conjunt… Mensal (Trimestre M… #> 13 SI Sistema Nacional de Pesqu… Ativa Conjunt… Mensal #> 14 CQ Pesquisa Trimestral do Co… Quarte… Ativa Conjunt… Trimestral #> 15 IQ Índice Nacional de Preços… Ativa Conjunt… Mensal #> 16 PZ Pesquisa Industrial Mensa… Ativa Conjunt… Mensal #> 17 LA Levantamento Sistemático … System… Ativa Conjunt… Mensal #> # ℹ 1 more variable: publication_frequency # Check which periods have metadata for the Censo Demográfico ibge_survey_periods("CD") #> ℹ Fetching survey catalog from IBGE Metadata API... #> ✔ Fetching survey catalog from IBGE Metadata API... [79ms] #> #> ℹ Fetching periods for survey CD from IBGE Metadata API... #> ✔ Fetching periods for survey CD from IBGE Metadata API... [69ms] #> #> ✔ 2 periods found for survey "CD". #> # A tibble: 2 × 3 #> year month order #> #> 1 2010 NA NA #> 2 2022 NA NA # Get full institutional metadata for a specific period meta_cd <- ibge_survey_metadata("CD", year = 2022) #> ℹ Fetching metadata for CD (2022) from IBGE Metadata API... #> ✔ Fetching metadata for CD (2022) from IBGE Metadata API... [89ms] #> #> ✔ Survey "CD" (2022): 1 metadata occurrence. meta_cd #> #> ── CD ────────────────────────────────────────────────────────────────────────── #> Status: Ativa #> Category: Estrutural #> Type: Censo demográfico #> Area: Estatísticos #> Started: 01/01/1872 #> #> ── Thematic classifications (19) ── #> #> ── Metadata occurrences (1) ── #> #> Use `meta$occurrences` to explore the full metadata. #> Fields: "sigla", "data_inicio_coleta", "data_fim_coleta", #> "data_previsao_divulgacao", "historico", "historico_ingles", "objetivo", and #> "objetivo_ingles" ... and 69 more # Explore methodology fields names(meta_cd$occurrences[[1]]) #> [1] "sigla" #> [2] "data_inicio_coleta" #> [3] "data_fim_coleta" #> [4] "data_previsao_divulgacao" #> [5] "historico" #> [6] "historico_ingles" #> [7] "objetivo" #> [8] "objetivo_ingles" #> [9] "populacao_alvo" #> [10] "populacao_alvo_ingles" #> [11] "metodologia" #> [12] "metodologia_ingles" #> [13] "notas_ocorrencia" #> [14] "notas_ocorrencia_ingles" #> [15] "ind_divulgacao" #> [16] "principais_variaveis" #> [17] "principais_variaveis_ingles" #> [18] "niveis_divulgacao" #> [19] "niveis_divulgacao_ingles" #> [20] "nivel_geografico_abrangencia" #> [21] "nivel_geografico_abrangencia_ingles" #> [22] "nivel_geografico_desagregacao" #> [23] "nivel_geografico_desagregacao_ingles" #> [24] "instituicoes_responsaveis" #> [25] "periodos_referencia" #> [26] "tipos_dados" #> [27] "unidades_informante" #> [28] "unidades_investigacao" #> [29] "unidades_analise" #> [30] "tecnicas_coleta" #> [31] "formas_disseminacao" #> [32] "nivel_desagregacao" #> [33] "nivel_desagregacao_ingles" #> [34] "instrumentos_coleta" #> [35] "palavras_chave" #> [36] "palavras_chave_ingles" #> [37] "definicao_fatores_expansao" #> [38] "definicao_fatores_expansao_ingles" #> [39] "notas_coleta_dados" #> [40] "notas_coleta_dados_ingles" #> [41] "supervisao" #> [42] "supervisao_ingles" #> [43] "critica_imputacao" #> [44] "critica_imputacao_ingles" #> [45] "outras_info_processamento" #> [46] "outras_info_processamento_ingles" #> [47] "calculo_erro_amostral" #> [48] "calculo_erro_amostral_ingles" #> [49] "outras_info_qualidade" #> [50] "outras_info_qualidade_ingles" #> [51] "autoridade_acesso" #> [52] "autoridade_acesso_ingles" #> [53] "confidencialidade" #> [54] "confidencialidade_ingles" #> [55] "condicoes_acesso" #> [56] "condicoes_acesso_ingles" #> [57] "referencia_citacao_fonte" #> [58] "referencia_citacao_fonte_ingles" #> [59] "base_legal" #> [60] "base_legal_ingles" #> [61] "direitos_autorais" #> [62] "direitos_autorais_ingles" #> [63] "contato" #> [64] "contato_ingles" #> [65] "procedimento_amostragem" #> [66] "procedimento_amostragem_ingles" #> [67] "ocorrencias_variavel" #> [68] "qualidade" #> [69] "observacoes_sidra" #> [70] "observacoes_sidra_ingles" #> [71] "recomendacoes_internacionais_referencias_metodologicas" #> [72] "recomendacoes_internacionais_referencias_metodologicas_ingles" #> [73] "ano" #> [74] "mes" #> [75] "ordem_periodo" #> [76] "nome_ocorrencia" #> [77] "nome_ocorrencia_ingles" ``` Survey codes are validated before each request. If you use a wrong code, the error suggests similar alternatives: ``` r ibge_survey_periods("PMS") #> Error: #> ! Survey code "PMS" not found in the IBGE catalog. #> ℹ Did you mean one of these? #> • PM - Pesquisa de Informações Básicas Municipais #> • AM - Pesquisa de Assistência Médico-Sanitária #> • PT - Pesquisa de Serviços de Tecnologia da Informação #> • TS - Conta Satélite da Saúde #> • VS - Produção da Extração Vegetal e da Silvicultura #> → Use `ibge_surveys()` to see all 100 valid codes. ``` ## Special values The `value` column may contain special codes instead of numbers (`-`, `..`, `...`, `X`), so it comes through as a character column. Use `parse_ibge_value()` to convert it to numeric in one step — its documentation (`?parse_ibge_value`) has the full table of codes and how each one is handled: ``` r ibge_variables(7060, variable = 63, localities = "BR") |> mutate(value = parse_ibge_value(value)) #> ℹ Fetching metadata for aggregate 7060 from IBGE API... #> ✔ Fetching metadata for aggregate 7060 from IBGE API... [114ms] #> #> ✔ Aggregate 7060: 4 variables, #> 1 classification, 457 categories. #> ℹ Fetching variables for aggregate 7060 from IBGE API... #> ✔ Fetching variables for aggregate 7060 from IBGE API... [104ms] #> #> ✔ 6 records retrieved. #> # A tibble: 6 × 9 #> variable_id variable_name variable_unit classification_315 locality_id #> #> 1 63 IPCA - Variação mens… % Índice geral 1 #> 2 63 IPCA - Variação mens… % Índice geral 1 #> 3 63 IPCA - Variação mens… % Índice geral 1 #> 4 63 IPCA - Variação mens… % Índice geral 1 #> 5 63 IPCA - Variação mens… % Índice geral 1 #> 6 63 IPCA - Variação mens… % Índice geral 1 #> # ℹ 4 more variables: locality_name , locality_level , period , #> # value ``` --- This vignette was last built on 2026-09-22 against the live IBGE API.