Skip to contents

realestatebr 1.0.1

Source: vignettes/articles/realestatebr-1-0-1.Rmd
realestatebr-1-0-1.Rmd

I am happy to announce that realestatebr 1.0.1 is the first version of the package on CRAN. The goal of realestatebr is to provide a unified interface to Brazilian real estate data from many public sources, delivering everything in a tidy tibble format.

install.packages("realestatebr")

This release marks a milestone in how the package is used. The headline change is the move from a long list of individual get_*() functions to a single entry point, get_dataset().

One function instead of many

Earlier versions exposed a separate function for each source. To read financing data from ABECIP you called get_abecip_indicators(), for the Central Bank series you called get_bcb_series(), and so on. Every source had its own function, its own arguments, and its own quirks.

# The old way, no longer available
abecip <- get_abecip_indicators(table = "sbpe")
bcb <- get_bcb_series(table = "price")
secovi <- get_secovi()

Separate functions helped with discoverability and documentation, but they stopped scaling as the number of datasets grew. From 1.0.1 onwards, get_dataset() retrieves any dataset in the package.

library(realestatebr)

# The new way
abecip <- get_dataset("abecip", table = "sbpe")
bcb <- get_dataset("bcb_series", table = "core")
secovi <- get_dataset("secovi", table = "all")

When the table argument is omitted, get_dataset() returns the default table for that dataset.

# Returns the default table
abecip <- get_dataset("abecip")

The individual get_*() functions are no longer part of the public interface. The table below maps the most common ones to their get_dataset() equivalent.

Old function New call
get_abecip_indicators("sbpe") get_dataset("abecip", "sbpe")
get_abrainc_indicators() get_dataset("abrainc")
get_bcb_realestate() get_dataset("bcb_realestate")
get_bcb_series("price") get_dataset("bcb_series", "core")
get_secovi() get_dataset("secovi")
get_rppi("fipezap") get_dataset("rppi", "fipezap")
get_rppi_bis() get_dataset("rppi_bis")

Discovering what is available

Since the names of datasets and tables are now arguments, you need a way to find them. list_datasets() returns a tibble describing every dataset, its source, and the tables it contains.

datasets <- list_datasets()
datasets

The currently active datasets cover financing and credit, launches and sales, macroeconomic series, and a wide range of residential property price indices.

Dataset Source Tables
abecip ABECIP sbpe, units, cgi
abrainc ABRAINC / FIPE indicator, radar, leading
bcb_realestate Banco Central do Brasil accounting, application, indices, sources, units
bcb_series Banco Central do Brasil core, primary, secondary, tertiary, full
fgv_ibre FGV IBRE —
rppi FipeZap, IVG-R, IGMI-R, IQA, IVAR, SECOVI-SP sale, rent, and individual indices
rppi_bis Bank for International Settlements selected, detailed_monthly, detailed_quarterly
secovi SECOVI-SP condo, rent, launch, sale

Users of previous versions might miss the tables from CBIC (Câmara Brasileira da Indústria da Construção) and from Registro de Imóveis (property_records). Registro de Imóveis no longer publishes consolidated Excel reports; the data now comes in a different format, which the package does not yet read. CBIC paywalled all of its previously open datasets. Several CBIC tables were built on open sources, so they may return in a future release.

Choosing where data comes from

get_dataset() resolves data in two tiers. By default it reads a pre-processed asset from the package’s GitHub release, which is fast and updated automatically by a weekly pipeline. If that asset is unavailable, it falls back to a fresh download from the original source. The source argument lets you control this behaviour.

# Auto (default): GitHub release, then fresh download as a fallback
data <- get_dataset("abecip")

# Pre-processed asset from the package's GitHub release
data <- get_dataset("abecip", source = "github")

# Fresh download straight from the original source
data <- get_dataset("abecip", source = "fresh")

Repeated calls within one R session are served from an in-memory store, so asking for the same dataset twice does not download it twice. Use clear_session_cache() to drop that store without restarting R.

This release also reworks the caching architecture so that the package never writes outside the R session’s temporary directory, in line with CRAN policy. The earlier user-level disk cache and its helper functions have been removed.

A worked example

The example below reads the FipeZap index and plots the year-on-year change in sale and rent prices for the city of São Paulo.

library(dplyr)
library(ggplot2)

plot_font <- if (
  requireNamespace("systemfonts", quietly = TRUE) &&
    any(systemfonts::system_fonts()[["family"]] == "Avenir")
) {
  "Avenir"
} else {
  "sans"
}

fipezap <- get_dataset("rppi", table = "fipezap")

rppi_spo <- fipezap |>
  filter(
    name_muni == "São Paulo",
    market == "residential",
    rooms == "total",
    variable == "acum12m",
    date >= as.Date("2019-01-01")
  )

ggplot(rppi_spo, aes(x = date, y = value, color = rent_sale)) +
  geom_line(lwd = 0.8) +
  geom_hline(yintercept = 0) +
  scale_x_date(date_breaks = "1 year", date_labels = "%Y") +
  labs(
    title = "São Paulo Property Price Index",
    x = NULL,
    y = "YoY chg. (%)",
    color = ""
  ) +
  theme_minimal(base_family = plot_font) +
  theme(legend.position = "bottom")

Breaking changes

Consolidating the interface meant retiring a few datasets that could not be maintained reliably. The cbic, property_records, nre_ire, and itbi datasets have been removed. property_records and cbic may return, as noted above, but nre_ire and itbi will not. nre_ire resists automation and costs more upkeep than it returns. itbi was an experiment in bringing large transaction-level datasets into the package; that scale of data belongs in a package of its own.

The bcb_series and rppi datasets also changed shape. bcb_series now returns a compact set of columns and accepts a hierarchy level such as "core" or "primary" instead of a category name, while the stacked rppi table gains transaction_type and source columns. See the changelog for the full list.

Learn more

To go further, read the Getting Started article for a tour of the core interface, or Working with RPPI for a deeper look at the property price indices. Bug reports and suggestions are welcome on GitHub.