Package {realestatebr}

realestatebr: Import Brazilian Real Estate Data into R

Description

Provides access to Brazilian real estate market data from multiple official sources: the Central Bank of Brazil (BCB) https://www.bcb.gov.br/, the Brazilian Association of Real Estate Developers (ABRAINC) https://abrainc.org.br/, the Brazilian Association of Real Estate Credit and Savings Entities (ABECIP) https://www.abecip.org.br/, the Getulio Vargas Foundation (FGV) https://portalibre.fgv.br/, and the Bank for International Settlements (BIS) https://www.bis.org/.

Author(s)

Maintainer: Vinicius Oike Reginatto viniciusoike@gmail.com [copyright holder]

See Also

Useful links:

• https://github.com/viniciusoike/realestatebr

• https://viniciusoike.github.io/realestatebr/

• Report bugs at https://github.com/viniciusoike/realestatebr/issues

Character mappings for consistent encoding

Description

Maps ASCII-key identifiers to their UTF-8 Portuguese equivalents. Keys are kept as plain ASCII for easy programmatic lookup; values are UTF-8 strings as supported by Encoding: UTF-8 in DESCRIPTION.

Usage

.ENCODING_MAP

Format

An object of class list of length 13.

Clean a Single SBPE-Format Table

Description

Clean a Single SBPE-Format Table

Usage

abecip_clean_sbpe_table(df)

Arguments

Value

Cleaned tibble

Apply Table Filtering to Loaded Dataset

Description

Applies table/category filtering logic for datasets that support multiple tables. Used by both get_from_local_cache() and get_from_github_cache().

Usage

apply_table_filtering(data, name, table)

Arguments

Value

Filtered dataset

Attach Standard Metadata to Dataset

Description

Attaches standardized metadata attributes to a dataset. Consolidates metadata attachment logic used across all dataset functions.

Usage

attach_dataset_metadata(
  data,
  source = c("web", "cache", "github", "github_cache"),
  category = NULL,
  extra_info = list()
)

Arguments

Value

The data with metadata attributes attached.

Real Estate Players listed on B3

Description

List of main Brazilian real estate players listed on B3.

Usage

b3_real_estate

Format

b3_real_estate

A tibble with 38 rows and 3 columns:

symbol

Stock ticker.

name

Full company name.

name_short

A shorter version of the company name.

Source

B3

Brazilian Central Bank Series Metadata

Description

A table with metadata for BCB economic series. Use with get_dataset("bcb_series"). The hierarchy column controls which series are returned by default: pass table = "core" for the most relevant real estate series, or a broader level for more macroeconomic context (see get_dataset).

Usage

bcb_metadata

Format

bcb_metadata

A data frame with 140 rows and 11 columns:

code_bcb

Numeric code identifying the series.

bcb_category

Category of the series.

name_simplified

Simplified name of the series.

name_pt

Full name of the series in Portuguese.

name

Full name of the series in English.

unit

Unit of the series.

frequency

Frequency of the series.

first_value

Date of the first available observation.

last_value

Date of the last available observation.

source

Source of the series.

hierarchy

Integer relevance tier: 1 = core real estate credit series; 2 = primary (key macro series such as SELIC, IPCA, INCC); 3 = secondary (broader macro context); 4 = tertiary (less relevant or discontinued series).

Source

Brazilian Central Bank (BCB)

Check Cache Status

Description

Display status of all locally cached datasets. Uses relaxed staleness thresholds (2x update frequency) to identify datasets that may benefit from updating.

Usage

check_cache_status(verbose = TRUE)

Arguments

Value

Tibble with cache status information (invisibly)

Examples

check_cache_status()

status <- check_cache_status(verbose = FALSE)

Check GitHub Connection

Description

Tests if GitHub is accessible for downloading release assets.

Usage

check_github_available()

Value

Logical. TRUE if GitHub is accessible

Clean SBPE Data from Abecip Excel File

Description

Clean SBPE Data from Abecip Excel File

Usage

clean_abecip_sbpe(temp_path)

Arguments

Value

A tibble with processed SBPE data

Clean Units Data from Abecip Excel File

Description

Clean Units Data from Abecip Excel File

Usage

clean_abecip_units(temp_path)

Arguments

Value

A tibble with processed units data

Process BIS Detailed CSV Data

Description

Reads the flat CSV, parses compound columns, then splits by frequency with appropriate date parsing for each.

Usage

clean_bis_detailed(csv_path, quiet)

Arguments

Value

Named list with elements: monthly, quarterly, annual, halfyearly

Clean BIS Selected CSV Data

Description

Reads the column-oriented CSV from the BIS SPP dataset, pivots date columns to long format, and standardises column names.

Usage

clean_bis_selected(csv_path, quiet)

Arguments

Value

Processed BIS selected data tibble

Clear User Cache

Description

Removes cached datasets from user directory.

Usage

clear_user_cache(dataset_names = NULL, confirm = TRUE)

Arguments

Value

Logical. TRUE if successful

Examples

clear_user_cache("abecip")

Debug-Level Messaging

Description

Displays informational messages only when debug mode is enabled. This function is a wrapper around cli::cli_inform() that respects the debug mode setting.

Usage

cli_debug(message, ...)

Arguments

Details

This function should be used for detailed processing messages that are useful for development and debugging but would be too verbose for end-users. Messages are only shown when debug mode is enabled via is_debug_mode().

See Also

is_debug_mode()

User-Level Messaging

Description

Displays concise informational messages for end-users. This function shows a simplified, clean message unless the user has requested verbose output via the quiet parameter.

Usage

cli_user(message, quiet = FALSE, ...)

Arguments

Details

This function should be used for essential status messages that provide value to end-users, such as final results or major milestones. The message is shown unless explicitly suppressed by quiet=TRUE.

Brazilian city identifier table

Description

A table with official IBGE identifiers for all Brazilian cities.

Usage

dim_city

Format

An object of class tbl_df (inherits from tbl, data.frame) with 5570 rows and 9 columns.

Details

A tibble with 5,570 rows and 8 columns:

code_muni

7-digit IBGE code identifying the city.

name_muni

Name of the city.

code_state

2-digit IBGE code identifying the state.

name_state

Name of the state.

code_region

1-digit IBGE code identifying the region

name_region

Name of the region

name_simplified

Simplified version of the city name for easier subsetting.

Source

IBGE (Brazilian Institute of Geography and Statistics)

Download Abecip Excel File

Description

Scrapes the given page to find the download link, then downloads the Excel file using the shared download_excel() helper.

Usage

download_abecip_file(
  url_page,
  xpath,
  file_prefix,
  quiet = FALSE,
  max_retries = 3L
)

Arguments

Value

Path to the downloaded temporary file

Download SBPE Excel File from Abecip

Description

Download SBPE Excel File from Abecip

Usage

download_abecip_sbpe(quiet = FALSE, max_retries = 3L)

Arguments

Value

Path to the downloaded temporary file

Download Units Excel File from Abecip

Description

Download Units Excel File from Abecip

Usage

download_abecip_units(quiet = FALSE, max_retries = 3L)

Arguments

Value

Path to the downloaded temporary file

Download raw BCB real estate data from the API

Description

Download raw BCB real estate data from the API

Usage

download_bcb_realestate(quiet = FALSE, max_retries = 3L)

Arguments

Value

Raw tibble from BCB API endpoint

Download BCB Series Data with Robust Error Handling

Description

Downloads BCB series data with per-series retry logic. Uses purrr::possibly() to collect failures without aborting, then reports any failed series after the full map completes.

Usage

download_bcb_series(codes_bcb, date_start, quiet, max_retries, ...)

Arguments

Value

A long-format tibble with columns date, value, and code_bcb.

Download BIS RPPI Detailed ZIP

Description

Download BIS RPPI Detailed ZIP

Usage

download_bis_detailed(quiet, max_retries)

Arguments

Value

Path to extracted CSV file

Download BIS RPPI Selected ZIP

Description

Download BIS RPPI Selected ZIP

Usage

download_bis_selected(quiet, max_retries)

Arguments

Value

Path to extracted CSV file

Download CSV File

Description

Downloads a CSV file to a temporary location with retry logic.

Usage

download_csv(
  url,
  min_size = 100,
  ssl_verify = TRUE,
  max_retries = 3,
  quiet = FALSE
)

Arguments

Value

Character. Path to downloaded CSV file.

Download and Validate Excel File

Description

Downloads an Excel file with validation of expected sheets and file size.

Usage

download_excel(
  url,
  expected_sheets = NULL,
  min_size = 1000,
  ssl_verify = TRUE,
  max_retries = 3,
  quiet = FALSE
)

Arguments

Value

Character. Path to downloaded and validated Excel file.

Download Dataset from GitHub Release

Description

Downloads a cached dataset from GitHub releases and saves to user cache.

Usage

download_from_github_release(dataset_name, overwrite = FALSE, quiet = FALSE)

Arguments

Value

Dataset or NULL if download fails

Download raw SECOVI-SP indicator tables

Description

Download raw SECOVI-SP indicator tables

Usage

download_secovi(table, quiet, max_retries)

Arguments

Value

Named list of scraped data tables

Download with Retry Logic

Description

Executes a download function with automatic retry on failure. Uses exponential backoff between retry attempts.

Usage

download_with_retry(fn, max_retries = 3, quiet = FALSE, desc = "Download")

Arguments

Value

Result from fn() if successful

Download and Extract File from ZIP Archive

Description

Downloads a ZIP archive, extracts a file matching file_pattern, validates its size, and returns the path to the extracted file.

Usage

download_zip(
  url,
  file_pattern = "\\.csv$",
  min_size = 1000,
  ssl_verify = TRUE,
  max_retries = 3,
  quiet = FALSE
)

Arguments

Value

Character. Path to the extracted file.

Character Encoding Utilities

Description

Internal utilities for consistent handling of Portuguese characters. The package uses UTF-8 encoding (declared in DESCRIPTION) throughout.

Ensure Cache Directory Exists

Description

Creates the user cache directory if it doesn't exist.

Usage

ensure_cache_dir()

Value

Character. Path to cache directory (invisibly)

Fallback to GitHub Cache on Download Failure

Description

Attempts to load a dataset from the GitHub release cache when a primary web download has failed. Returns NULL on miss so callers can decide whether to abort or degrade gracefully.

Usage

fallback_to_github_cache(dataset_name, quiet = FALSE)

Arguments

Value

A tibble if the GitHub cache is available, otherwise NULL.

Get Credit Indicators from Abecip

Description

Get Credit Indicators from Abecip

Usage

get_abecip_indicators(
  table = "sbpe",
  cached = FALSE,
  quiet = FALSE,
  max_retries = 3L
)

Arguments

Details

Downloads housing credit data from Abecip including SBPE monetary flows, financed units, and home-equity loan data.

Value

Either a named list (when table is 'all') or a tibble (for specific tables). The return includes metadata attributes:

download_info

List with download statistics

source

Data source used (web or cache)

download_time

Timestamp of download

Source

https://www.abecip.org.br

Import Indicators from the Abrainc-Fipe Report

Description

Import Indicators from the Abrainc-Fipe Report

Usage

get_abrainc_indicators(
  table = "indicator",
  cached = FALSE,
  quiet = FALSE,
  max_retries = 3L
)

Arguments

Details

Downloads data from the Abrainc-Fipe Indicators report including information on new launches, sales, delivered units, and market indicators.

Value

Either a named list (when table is 'all') or a tibble (for specific tables). The return includes metadata attributes:

download_info

List with download statistics

source

Data source used (web or cache)

download_time

Timestamp of download

Source

Abrainc-Fipe available at https://www.fipe.org.br/pt-br/indices/abrainc

Get Available Tables from Dataset Info

Description

Extract list of available tables/categories from dataset registry information

Usage

get_available_tables(dataset_info)

Arguments

Value

Character vector of available table names, or NULL if no categories

Import Real Estate data from the Brazilian Central Bank

Description

Imports real estate data from BCB including credit sources, applications, financed units, and real estate indices.

Usage

get_bcb_realestate(
  table = "all",
  cached = FALSE,
  quiet = FALSE,
  max_retries = 3L
)

Arguments

Value

Tibble with BCB real estate data. Includes metadata attributes: source, download_time.

Source

https://dadosabertos.bcb.gov.br/dataset/informacoes-do-mercado-imobiliario

Download macroeconomic time-series from BCB

Description

Download macroeconomic time-series from BCB

Usage

get_bcb_series(
  table = "core",
  cached = FALSE,
  date_start = as.Date("2010-01-01"),
  quiet = FALSE,
  max_retries = 3L,
  ...
)

Arguments

Details

Downloads macroeconomic time series from BCB. Series are organized by relevance to the Brazilian real estate market using a four-level hierarchy. The default ("core") returns the 40 most directly relevant series covering real estate credit concession, interest rates, and delinquency. Use broader levels to include macroeconomic context series.

Value

A 4-column tibble with columns date, code_bcb, name_simplified, and value. Series metadata is available in bcb_metadata.

Source

https://www3.bcb.gov.br/sgspub/localizarseries/localizarSeries.do?method=prepararTelaLocalizarSeries

Get Cache Age in Days

Description

Calculate how old a cached dataset is in days.

Usage

get_cache_age(dataset_name)

Arguments

Value

Numeric. Age in days, or NA if can't determine

Get Cache Metadata

Description

Returns metadata about cached datasets including download dates and versions.

Usage

get_cache_metadata(dataset_name = NULL)

Arguments

Value

List or tibble with metadata

Get GitHub Release Tag for Cache

Description

Returns the tag name for the release containing cached data.

Usage

get_cache_release_tag()

Value

Character. Release tag name

Get Cached File Path

Description

Returns the full path to a cached dataset file.

Usage

get_cached_file_path(dataset_name, extension = NULL)

Arguments

Value

Character. Full path to cached file, or NULL if not found

Get Cached Name for Dataset

Description

Maps dataset names to the cached file names used by load_from_user_cache()

Usage

get_cached_name(name, dataset_info, table = NULL)

Get Dataset

Description

Unified interface for accessing all realestatebr datasets with automatic fallback between data sources: user cache, GitHub releases, and fresh download.

Usage

get_dataset(
  name,
  table = NULL,
  source = "auto",
  date_start = NULL,
  date_end = NULL,
  max_age = NULL,
  ...
)

Arguments

Value

A tibble or named list, depending on the dataset. Use get_dataset_info to inspect the expected structure.

See Also

list_datasets for available datasets, get_dataset_info for dataset details.

Examples

abecip_data <- get_dataset("abecip")

sbpe_data <- get_dataset("abecip", table = "sbpe")

bcb_recent <- get_dataset("bcb_series", date_start = as.Date("2020-01-01"))

Get Dataset from Specific Source

Description

Internal function to get data from a specific source type.

Usage

get_dataset_from_source(
  name,
  dataset_info,
  source,
  table,
  date_start,
  date_end,
  ...
)

Arguments

Value

Dataset or error

Get Dataset Information

Description

Returns detailed metadata for a single dataset, including available tables and source information.

Usage

get_dataset_info(name)

Arguments

Value

A named list with the following elements:

metadata

Title, description, geography, frequency, and coverage.

categories

Available tables/subtables and their descriptions.

source_info

Source organization and URL.

technical_info

Cached file names and translation notes.

Examples

info <- get_dataset_info("abecip")
str(info)

Get Dataset with Fallback Strategy

Description

Internal function implementing the auto fallback strategy: cache -> GitHub -> fresh download

Usage

get_dataset_with_fallback(
  name,
  dataset_info,
  table,
  date_start,
  date_end,
  max_age = NULL,
  ...
)

Arguments

Value

Dataset or NULL if all methods fail

Get FGV IBRE Confidence Indicators

Description

Loads construction confidence indicators from FGV IBRE including confidence indices, expectation indicators, and INCC price indices.

Usage

get_fgv_ibre(table = "indicators", cached = TRUE, quiet = FALSE)

Arguments

Value

Tibble with FGV IBRE indicators. Includes metadata attributes: source, download_time.

Get Data from GitHub Cache

Description

Downloads dataset from GitHub releases to user cache, then loads it.

Usage

get_from_github_cache(name, dataset_info, table)

Get Data from Internal Function

Description

Calls internal dataset-specific functions (e.g., get_abecip_indicators) for fresh data downloads. These are the core internal functions, not legacy code.

Usage

get_from_internal_function(
  name,
  dataset_info,
  table,
  date_start,
  date_end,
  ...
)

Get Data from Local Cache

Description

Loads dataset from user-level cache directory.

Usage

get_from_local_cache(name, dataset_info, table)

Get GitHub Repository Information

Description

Returns the GitHub repository information for this package.

Usage

get_github_repo()

Value

Character. GitHub repo in format "owner/repo"

Get Stacked RPPI Data

Description

Get Stacked RPPI Data

Usage

get_rppi(table = "sale", cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

Stacks multiple Brazilian residential property price indices into a single tibble with consistent columns for easy comparison. Handles different RPPI sources (IGMI-R, IVG-R, FipeZap, IVAR, IQAIW) and standardizes their formats.

Sale stack: IGMI-R, IVG-R, FipeZap. Rent stack: IVAR, IQAIW, FipeZap. Use get_dataset("rppi", table) for individual indices (IQA, IQAIW, Secovi-SP, etc.).

Value

Tibble with columns: date, name_muni, index, chg, acum12m, source (plus transaction_type if table="all")

Get Residential Property Price Indices from BIS

Description

Downloads Residential Property Price Indices from BIS with support for selected series and detailed monthly/quarterly/annual/halfyearly datasets.

Usage

get_rppi_bis(
  table = "selected",
  cached = FALSE,
  quiet = FALSE,
  max_retries = 3L
)

Arguments

Value

Tibble with BIS RPPI data. Includes metadata attributes: source, download_time.

Source

https://data.bis.org/topics/RPP

Get FipeZap RPPI

Description

Get FipeZap RPPI

Usage

get_rppi_fipezap(city = "all", cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The FipeZap Index is a monthly median stratified index across ~20 Brazilian cities, based on online listings from Zap Imoveis. Includes residential and commercial markets, both sale and rent, stratified by number of rooms. The overall city index is a weighted sum of median prices by room/region. Residential index includes only apartments, studios, and flats. National index: name_muni == 'Brazil' (after standardization).

Value

Tibble with columns: date, name_muni, market, rent_sale, variable, rooms, value

Get the IGMI Sales Index

Description

Get the IGMI Sales Index

Usage

get_rppi_igmi(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The IGMI-R (Residential Real Estate Index) is a hedonic sales index based on bank appraisal reports, available for Brazil + 10 capital cities. Hedonic indices account for both composition bias and quality differentials across the housing stock. Maintained by ABECIP in partnership with FGV.

Value

Tibble with columns: date, name_muni, index, chg, acum12m

Get QuintoAndar Rental Index (IQA)

Description

Get QuintoAndar Rental Index (IQA)

Usage

get_rppi_iqa(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The IQA (QuintoAndar Rental Index) is a median stratified index for Rio de Janeiro and Sao Paulo, based on new rent contracts managed by QuintoAndar. Includes only apartments, studios, and flats. Note: IQA provides raw prices (not index numbers), so rent_price is the median rent per square meter.

Value

Tibble with columns: date, name_muni, rent_price, chg, acum12m

Get QuintoAndar ImovelWeb Rental Index (IQAIW)

Description

Get QuintoAndar ImovelWeb Rental Index (IQAIW)

Usage

get_rppi_iqaiw(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The IQAIW (Indice QuintoAndar ImovelWeb) is a rental index for major Brazilian cities. The index is based on both new rental contracts (managed by QuintoAndar) and online listings from QuintoAndar's listings (including ImovelWeb). The IQAIW was developed in 2023 and replaced the former IQA index. Given the change in methodology and data sources, the IQAIW is not directly comparable to the IQA index. Formally, the index is a hedonic double imputed index, controlling for quality changes using a flexible GAM specification with location variables. In this sense, the IQAIW is more theoretically sound than median stratified indices like FipeZap or the former IQA. The mixture of listings and contracts, however, lacks theoretical support and seems to be mainly driven by branding purposes. The ImovelWeb brand was purchased by QuintoAndar in 2021-22 and the IQAIW symbolizes the merging of both brands. In other words, the original IQA could've been improved simply by adopting a hedonic methodology, without the need to mix data sources.

Value

Tibble with columns: date, name_muni, index, chg, acum12m, price_m2

Get IVAR Rent Index

Description

Get IVAR Rent Index

Usage

get_rppi_ivar(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The IVAR (Residential Rent Variation Index) is a repeat-rent index from IBRE/FGV, comparing the same housing unit over time. Based on rental contracts from brokers. Available for 4 major cities (Sao Paulo, Rio, Porto Alegre, Belo Horizonte); the national index is a weighted average. More theoretically sound than IGP-M for rent contracts as it measures only rent prices.

Value

Tibble with columns: date, name_muni, index, chg, acum12m, name_simplified, abbrev_state

Note

IVAR data is only available from cache as the source data (FGV) is not accessible via web scraping. This function will automatically use cached data when source data is unavailable.

Get the IVGR Sales Index

Description

Get the IVGR Sales Index

Usage

get_rppi_ivgr(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

The IVG-R (Residential Real Estate Collateral Value Index) is a monthly median sales index based on bank appraisals, calculated by the Brazilian Central Bank (BCB series 21340). The index estimates long-run trends in home prices using the Hodrick-Prescott filter (lambda=3600) applied to major metropolitan regions. Note: Median indices suffer from composition bias and cannot account for quality changes across the housing stock.

Value

Tibble with columns: date, name_geo, index, chg, acum12m

References

Banco Central do Brasil (2018) "Indice de Valores de Garantia de Imoveis Residenciais Financiados (IVG-R). Seminario de Metodologia do IBGE."

Get Secovi-SP Rent Index

Description

Get Secovi-SP Rent Index

Usage

get_rppi_secovi_sp(cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

Secovi-SP rent price index for Sao Paulo. Wrapper around get_secovi() that extracts and formats rent price data as RPPI.

Value

Tibble with columns: date, name_muni, index, chg, acum12m

Import data from Secovi-SP

Description

Import data from Secovi-SP

Usage

get_secovi(table = "all", cached = FALSE, quiet = FALSE, max_retries = 3L)

Arguments

Details

Scrapes real estate data from SECOVI-SP including condominium fees, rental market data, launches, and sales information.

Value

A tibble with SECOVI-SP real estate data. The return includes metadata attributes:

download_info

List with download statistics

source

Data source used (web or cache)

download_time

Timestamp of download

Get User Cache Directory

Description

Returns the path to the user-level cache directory for realestatebr package. This directory is used to store downloaded datasets for faster subsequent access.

Usage

get_user_cache_dir()

Value

Character. Path to user cache directory

Generic Cache Handler with Fallback

Description

Attempts to load data from user cache with configurable fallback behavior. Consolidates cache loading logic used across all dataset functions.

Usage

handle_dataset_cache(
  dataset_name,
  table = NULL,
  quiet = FALSE,
  on_miss = c("download", "return_null", "error")
)

Arguments

Details

The function attempts to load data from the user cache directory (⁠~/.local/share/realestatebr/⁠ or equivalent). If a table parameter is provided, it extracts that specific table from the cached dataset.

On cache miss, behavior is controlled by on_miss:

• "return_null": Quietly returns NULL (caller handles fallback)

• "error": Throws error (use when cache is required)

• "download": Returns NULL with warning (triggers download in caller)

Value

The cached data (tibble or list), or NULL on cache miss.

Harmonize FipeZap Data for Stacking

Description

Harmonize FipeZap Data for Stacking

Usage

harmonize_fipezap_for_stacking(dat, transaction_type = NULL)

Arguments

Value

Harmonized tibble with standard RPPI columns

Check if piggyback is Available

Description

Checks if the piggyback package is installed and available for use.

Usage

has_piggyback()

Value

Logical. TRUE if piggyback is available

Check if Cache is Stale

Description

Determine if a cached dataset is older than its update schedule. Uses relaxed thresholds by default (2x update frequency) to avoid annoying users with unnecessary warnings.

Usage

is_cache_stale(dataset_name, warn_after_days = NULL)

Arguments

Value

Logical. TRUE if stale, FALSE if fresh, NA if can't determine

Check if GitHub Cache is Up to Date

Description

Compares local cache timestamp with GitHub release timestamp.

Usage

is_cache_up_to_date(dataset_name)

Arguments

Value

Logical. TRUE if local cache is up to date, FALSE if GitHub is newer, NA if can't determine

Check if Dataset is Cached

Description

Check if a dataset exists in the user cache.

Usage

is_cached(dataset_name)

Arguments

Value

Logical. TRUE if cached

Check if Debug Mode is Enabled

Description

Checks whether debug mode is enabled for detailed package messaging. Debug mode can be enabled via environment variable or package option.

Usage

is_debug_mode()

Details

Debug mode can be enabled in two ways (checked in order of precedence):

1. Environment variable: REALESTATEBR_DEBUG=TRUE

2. Package option: options(realestatebr.debug = TRUE)

When debug mode is enabled, all detailed processing messages are shown, including file-by-file progress, type detection, and intermediate steps. This is useful for development and troubleshooting.

Value

Logical. TRUE if debug mode is enabled, FALSE otherwise.

List Cached Files

Description

Lists all datasets currently in the user cache.

Usage

list_cached_files()

Value

Tibble with file information

List Available Datasets

Description

Returns a tibble describing all datasets available in the realestatebr package. Optionally filter by category, source organization, or geographic coverage.

Usage

list_datasets(category = NULL, source = NULL, geography = NULL)

Arguments

Value

A tibble with one row per dataset and the following columns:

name

Dataset identifier used with get_dataset.

title

English dataset name.

title_pt

Portuguese dataset name.

description

Brief description.

source

Data source organization.

geography

Geographic coverage.

frequency

Update frequency.

coverage

Time period covered.

available_tables

Comma-separated table names for multi-table datasets.

See Also

get_dataset for retrieving data, get_dataset_info for detailed metadata on a single dataset.

Examples

list_datasets()

list_datasets(source = "BCB")

List Available GitHub Assets

Description

Lists all cached datasets available on GitHub releases.

Usage

list_github_assets(quiet = FALSE)

Arguments

Value

Character vector of available asset names, or NULL if unavailable

Load and Process CGI Data from Bundled Excel File

Description

Load and Process CGI Data from Bundled Excel File

Usage

load_abecip_cgi(path)

Arguments

Value

A tibble with processed CGI data

Load Dataset Registry from YAML

Description

Internal function to load the dataset registry from the inst/extdata/datasets.yaml file.

Usage

load_dataset_registry()

Value

A list containing the parsed YAML registry

Load Dataset from User Cache

Description

Loads a dataset from the user-level cache directory.

Usage

load_from_user_cache(dataset_name, quiet = FALSE)

Arguments

Value

Dataset as tibble or list, or NULL if not found

Convert Registry to Tibble

Description

Internal function to convert the nested YAML registry structure to a flat tibble suitable for display and filtering.

Usage

registry_to_tibble(registry)

Arguments

Value

A tibble with dataset information

Resolve BCB Hierarchy Level to Series Codes

Description

Maps a hierarchy level name to a vector of BCB series codes. The levels are cumulative: "primary" includes all "core" series, "secondary" includes all "primary" series, and so on.

Usage

resolve_bcb_hierarchy(table)

Arguments

Value

Integer vector of BCB series codes.

RPPI Helper Functions

Description

Internal helper functions to reduce code duplication in RPPI functions. These are not exported and only used internally.

Save Cache Metadata

Description

Saves metadata about a cached dataset.

Usage

save_cache_metadata(dataset_name, format, source = NULL)

Arguments

Value

Logical. TRUE if successful

Save Dataset to User Cache

Description

Saves a dataset to the user-level cache directory.

Usage

save_to_user_cache(data, dataset_name, format = "rds", quiet = FALSE)

Arguments

Value

Logical. TRUE if successful

Show Dataset Import Message

Description

Display informative message about which table was imported and what's available

Usage

show_import_message(name, table_info)

Arguments

Standardize RPPI Structure

Description

Standardize RPPI Structure

Usage

standardize_rppi_structure(dat)

Arguments

Value

Standardized tibble with consistent columns

Check if Internal Function Supports table="all"

Description

Check if Internal Function Supports table="all"

Usage

supports_table_all(func_name)

Test function to verify encoding patterns work correctly

Description

Test function to verify encoding patterns work correctly

Usage

test_encoding_patterns()

Update Cache from GitHub

Description

Updates local cache for specific datasets if GitHub has newer versions.

Usage

update_cache_from_github(dataset_names = NULL, quiet = FALSE)

Arguments

Value

Named logical vector indicating success/failure for each dataset

Examples

update_cache_from_github("abecip")

update_cache_from_github()

Validate Abecip Data

Description

Validate Abecip Data

Usage

validate_abecip_data(data, type)

Arguments

Value

NULL (validates or errors)

Validate and Resolve Table Parameter

Description

Validates table parameter against available tables and resolves default table

Usage

validate_and_resolve_table(name, dataset_info, table = NULL)

Arguments

Value

List with resolved_table, available_tables, and is_default

Generic Data Validation

Description

Validates basic dataset requirements. Consolidates validation logic used across all dataset functions.

Usage

validate_dataset(
  data,
  dataset_name,
  required_cols = "date",
  min_rows = 1,
  check_dates = TRUE,
  max_future_days = 90
)

Arguments

Value

Invisible TRUE if all validations pass. Errors or warns otherwise.

Generic Parameter Validation for Dataset Functions

Description

Validates common parameters used across all dataset functions. This consolidates repetitive validation logic into a single reusable function.

Usage

validate_dataset_params(
  table,
  valid_tables,
  cached,
  quiet,
  max_retries,
  allow_all = TRUE
)

Arguments

Details

This function performs standard validation for:

• table: Must be character, length 1, in valid_tables (or "all" if allowed)

• cached: Must be logical, length 1

• quiet: Must be logical, length 1

• max_retries: Must be numeric, length 1, positive

Value

Invisible TRUE if all validations pass. Errors otherwise.