Package {tidyBdE}

Title:	Retrieve Time Series Data from 'Banco de España'
Version:	0.7.0
Description:	Tools for retrieving 'Banco de España' ('BdE') time series data as 'tibble' objects from bulk CSV files and the 'Statistics web service (API)'. Bulk CSV functions use stable 'BdE' sequential numbers, while API functions use API series codes. Catalog functions support discovery and local caching. Plotting helpers provide 'ggplot2' palettes, scales and themes. 'Banco de España' is the national central bank and, within the framework of the Single Supervisory Mechanism ('SSM'), the supervisor of the Spanish banking system alongside the European Central Bank. This package is not sponsored, endorsed or administered by 'Banco de España'.
License:	GPL (≥ 3)
URL:	https://ropenspain.github.io/tidyBdE/, https://github.com/rOpenSpain/tidyBdE
BugReports:	https://github.com/rOpenSpain/tidyBdE/issues
Depends:	R (≥ 4.1.0)
Imports:	cli, dplyr (≥ 0.7.0), ggplot2 (≥ 3.5.0), jsonlite, lifecycle, readr (≥ 1.0.0), scales (≥ 1.1.0), tibble (≥ 3.0.0), tidyr, utils
Suggests:	knitr, quarto, testthat (≥ 3.0.0)
VignetteBuilder:	quarto
Config/Needs/coverage:	covr
Config/Needs/website:	cpp11, devtools, progress, reactable, remotes, styler, tidyverse, ropenspain/rostemplate
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/testthat/parallel:	true
Copyright:	See file inst/COPYRIGHTS
Encoding:	UTF-8
LazyData:	true
X-schema.org-applicationCategory:	Macroeconomics
X-schema.org-isPartOf:	https://ropenspain.es/
X-schema.org-keywords:	api, bde, cran, ggplot2, macroeconomics, r, r-package, ropenspain, rstats, series-data, spain
NeedsCompilation:	no
Packaged:	2026-07-06 17:11:16 UTC; diego
Author:	Diego H. Herrero [aut, cre, cph], Banco de España [cph] (Data copyright holder)
Maintainer:	Diego H. Herrero <dev.dieghernan@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-06 17:30:02 UTC

tidyBdE: Retrieve Time Series Data from 'Banco de España'

Description

Tools for retrieving 'Banco de España' ('BdE') time series data as 'tibble' objects from bulk CSV files and the 'Statistics web service (API)'. Bulk CSV functions use stable 'BdE' sequential numbers, while API functions use API series codes. Catalog functions support discovery and local caching. Plotting helpers provide 'ggplot2' palettes, scales and themes. 'Banco de España' is the national central bank and, within the framework of the Single Supervisory Mechanism ('SSM'), the supervisor of the Spanish banking system alongside the European Central Bank. This package is not sponsored, endorsed or administered by 'Banco de España'.

Author(s)

Maintainer: Diego H. Herrero dev.dieghernan@gmail.com (ORCID) [copyright holder]

Authors:

• Diego H. Herrero dev.dieghernan@gmail.com (ORCID) [copyright holder]

Other contributors:

• Banco de España (ROR) (Data copyright holder) [copyright holder]

See Also

Useful links:

• https://ropenspain.github.io/tidyBdE/

• https://github.com/rOpenSpain/tidyBdE

• Report bugs at https://github.com/rOpenSpain/tidyBdE/issues

Load, update and search BdE catalog metadata

Description

These functions manage BdE time series catalog metadata from the bulk CSV files published by Banco de España.

bde_catalog_load() loads time series catalog metadata into a tibble, bde_catalog_update() refreshes the cached catalog files and bde_catalog_search() searches catalog metadata for keywords.

Usage

bde_catalog_load(
  catalog = c("ALL", "BE", "SI", "TC", "TI", "PB"),
  parse_dates = TRUE,
  cache_dir = NULL,
  update_cache = FALSE,
  verbose = FALSE
)

bde_catalog_update(
  catalog = c("ALL", "BE", "SI", "TC", "TI", "PB"),
  cache_dir = NULL,
  verbose = FALSE
)

bde_catalog_search(pattern, ...)

Arguments

Details

Accepted values for catalog are:

Use "ALL" as a shorthand for loading or updating all catalogs at once.

If the requested catalog is not cached, bde_catalog_load() calls bde_catalog_update().

Note: BdE catalog metadata is currently available in Spanish only. Therefore, search terms passed to bde_catalog_search() must be in Spanish to retrieve results.

bde_catalog_search() uses base::grep() to find matches in the catalog metadata. You can pass regular expressions to broaden the search.

Value

bde_catalog_load() returns a tibble with the requested time series catalog metadata. See vignette("csv_manual", package = "tidyBdE") for details.

bde_catalog_update() returns an invisible list of download results.

bde_catalog_search() returns a tibble with matching catalog rows.

Source

Banco de España time series bulk data download.

See Also

• bde_series_load() and bde_series_full_load() load bulk CSV series.

• bde_series_api_load() and bde_series_api_latest() retrieve series through the Statistics web service (API).

Examples

bde_catalog_load("TI", verbose = TRUE)

# Simple search. Search terms must be in Spanish.
# PIB [es] == GDP [en].
bde_catalog_search("PIB")

# Search with a single complex condition.
bde_catalog_search("Francia(.*)PIB")

# Search with multiple complex conditions.
bde_catalog_search("Francia(.*)PIB|Italia(.*)PIB|Alemania(.*)PIB")

bde_catalog_update("TI", verbose = TRUE)

Check access to BdE resources

Description

Checks whether R can access BdE resources at https://www.bde.es/webbe/en/estadisticas/recursos/descargas-completas.html.

Usage

bde_check_access()

Value

A logical value indicating whether BdE resources are reachable.

Examples

bde_check_access()

Database of selected Spanish macroeconomic indicators

Description

Minimal metadata for the selected Spanish macroeconomic indicators available through the convenience functions in tidyBdE. See indicator wrappers. Full catalog metadata is available with bde_catalog_load().

Format

A tibble of 9 rows and 8 columns with the following fields:

tidyBdE_fun

Function name. See indicator wrappers.

Numero_secuencial

Sequential number. See bde_series_load().

Nombre_de_la_serie

API series code. See API series functions.

Descripcion_de_la_serie

Description of the series in Spanish.

Fecha_de_la_primera_observacion

Starting date of the indicator.

Fecha_de_la_ultima_observacion

Most recent date available.

Fuente

Data source.

Details

See Also

vignette("csv_manual", package = "tidyBdE").

Selected indicators and metadata: bde_indicators

Examples

data("bde_ind_db")
bde_ind_db

Selected Spanish macroeconomic indicators

Description

Retrieve selected Spanish macroeconomic indicators. Metadata is available in bde_ind_db.

Usage

bde_ind_gdp_var(series_label = "GDP_YoY", ...)

bde_ind_unemployment_rate(series_label = "Unemployment_Rate", ...)

bde_ind_euribor_12m_monthly(series_label = "Euribor_12M_Monthly", ...)

bde_ind_euribor_12m_daily(series_label = "Euribor_12M_Daily", ...)

bde_ind_cpi_var(series_label = "Consumer_price_index_YoY", ...)

bde_ind_ibex_monthly(series_label = "IBEX_index_month", ...)

bde_ind_ibex_daily(series_label = "IBEX_index_day", ...)

bde_ind_gdp_quarterly(series_label = "GDP_quarterly_value", ...)

bde_ind_population(series_label = "Population_Spain", ...)

Arguments

Details

These functions are convenient wrappers for bde_series_load() that retrieve specific series. Use ⁠verbose = TRUE, extract_metadata = TRUE⁠ to inspect the metadata and source.

Value

A tibble with the requested indicator series.

Note

These functions attempt to parse columns as double values. For some time series, a warning may be displayed if parsing fails. Set parse_numeric = FALSE to disable numeric parsing.

Source

Banco de España time series bulk data download.

See Also

bde_series_load() for loading arbitrary bulk CSV series and bde_catalog_search() for finding series in catalog metadata.

Selected indicators and metadata: bde_ind_db

Examples

bde_ind_gdp_var()

Parse dates from strings

Description

Parse strings representing dates with as.Date(). This function is tailored to date formats used in this package and may not parse other datasets. See Examples for supported formats.

Usage

bde_parse_dates(dates_to_parse)

Arguments

Details

Date formats

See vignette("csv_manual", package = "tidyBdE") for details.

Value

A vector of Date values.

See Also

• bde_catalog_load() and bde_series_load() use this parser.

• as.Date() provides base R date conversion.

Examples

# Supported formats.
would_parse <- c(
  "02 FEB2019", "15 ABR 1890", "MAR 2020", "ENE2020",
  "2020", "12-1993", "01-02-2014", "01/02/1990"
)

parsed_ok <- bde_parse_dates(would_parse)

class(parsed_ok)

tibble::tibble(raw = would_parse, parsed = parsed_ok)

# Unsupported formats.

wont_parse <- c("JAN2001", "2010-01-12", "01 APR 2017", "01/31/1990")

parsed_fail <- bde_parse_dates(wont_parse)

class(parsed_fail)

tibble::tibble(raw = wont_parse, parsed = parsed_fail)

Load BdE time series from bulk CSV files

Description

These functions load BdE time series from the bulk CSV files published by Banco de España.

bde_series_load() extracts one or more series by their stable sequential number. bde_series_full_load() loads a complete bulk CSV file and returns all series included in that file.

See vignette("csv_manual", package = "tidyBdE") for details.

Usage

bde_series_load(
  series_code,
  series_label = NULL,
  out_format = "wide",
  parse_dates = TRUE,
  parse_numeric = TRUE,
  cache_dir = NULL,
  update_cache = FALSE,
  verbose = FALSE,
  extract_metadata = FALSE
)

bde_series_full_load(
  series_csv,
  parse_dates = TRUE,
  parse_numeric = TRUE,
  cache_dir = NULL,
  update_cache = FALSE,
  verbose = FALSE,
  extract_metadata = FALSE
)

Arguments

Value

bde_series_load() returns a tibble with a Date column:

• With out_format = "wide", each series is presented in a separate column with the name defined by series_label.

• With out_format = "long", the tibble has two additional columns: serie_name contains the label of each series; serie_value contains the corresponding value.

"wide" format is more suitable for exporting to a CSV file; "long" format is more suitable for creating plots with ggplot2::ggplot(). See also tidyr::pivot_longer() and tidyr::pivot_wider().

bde_series_full_load() returns a tibble with a Date column and the aliases of the time series columns as described in catalog metadata. See bde_catalog_load() and vignette("csv_manual", package = "tidyBdE") for details.

About BdE file naming

A series alias is a positional code that identifies the location, column or row of a series in a table. An alias is unique within its context but is not stable because it may change when a series moves.

A single time series may appear in different tables, so it can have several aliases. Use bde_series_full_load() when you need to work with aliases or load a complete file.

The series alias is also used in full CSV files. For example, table be_6_1 represents Table 1, Chapter 6 of the Statistical Bulletin ("BE"). Although it is unique, it is subject to change, for example when a new table is inserted before it.

Series identifiers

BdE identifies each series with a stable sequential number (Numero_secuencial) in bulk CSV files and an API series code (Nombre_de_la_serie) in the Statistics web service. bde_series_load() accepts stable sequential numbers in series_code. bde_series_api_latest() and bde_series_api_load() use the same argument for API series codes. Use bde_catalog_load() or bde_catalog_search() to find both identifiers.

Note

These functions attempt to parse columns as double values. For some time series, a warning may be displayed if parsing fails. Set parse_numeric = FALSE to disable numeric parsing.

Source

Banco de España time series bulk data download.

See Also

• bde_catalog_load() and bde_catalog_search() help find stable sequential numbers.

• Indicator wrappers retrieve commonly used Spanish macroeconomic series.

Time series functions: bde_series_api

Examples

# Show metadata.
bde_series_load(573234, verbose = TRUE, extract_metadata = TRUE)

# Load data.
bde_series_load(573234, extract_metadata = FALSE)

# Load multiple series.
bde_series_load(c(573234, 573214),
  series_label = c("US/EUR", "GBP/EUR"),
  extract_metadata = TRUE
)

wide <- bde_series_load(c(573234, 573214),
  series_label = c("US/EUR", "GBP/EUR")
)

# Show wide output.
wide

# Show long output.
long <- bde_series_load(c(573234, 573214),
  series_label = c("US/EUR", "GBP/EUR"),
  out_format = "long"
)

long

# Use with ggplot2.
library(ggplot2)

ggplot(long, aes(Date, serie_value)) +
  geom_line(aes(group = serie_name, color = serie_name)) +
  scale_color_bde_d() +
  theme_tidybde()

# Show metadata for a complete bulk CSV file.
bde_series_full_load("TI_1_1.csv", extract_metadata = TRUE)

# Load a complete bulk CSV file.
bde_series_full_load("TI_1_1.csv")

Load BdE time series from the Statistics web service (API)

Description

These functions retrieve BdE time series using theStatistics web service (API).

The API is a JSON web service that provides URL-based access to information available in the Statistics section of Banco de España and the BIEST application.

The API defines two request types. bde_series_api_latest() uses the Latest Data request to obtain the latest published observation for one or more series. bde_series_api_load() uses the Series List request to obtain the details of one or more complete series and their metadata.

Usage

bde_series_api_latest(series_code, language = c("en", "es"), verbose = FALSE)

bde_series_api_load(
  series_code,
  series_label = NULL,
  out_format = "wide",
  language = c("en", "es"),
  time_range = NULL,
  verbose = FALSE,
  extract_metadata = FALSE
)

Arguments

Details

Allowed time_range values depend on the series frequency:

• Daily frequency (D): "3M" (last 3 months), "12M" and "36M".

• Monthly frequency (M): "30M", "60M" and "MAX" (entire series).

• Quarterly frequency (Q): "30M", "60M" and "MAX".

• Annual frequency (A): "60M" and "MAX".

If time_range is not specified, the request returns the smallest range for the series frequency. For example, monthly series return "30M".

Value

bde_series_api_latest() returns a tibble with the latest published observation for each valid series. It includes fields returned by the Latest Data request such as serie, descripcionCorta, codFrecuencia, decimales, simbolo, tendencia, fechaValor and valor.

bde_series_api_load() returns a tibble. When extract_metadata = FALSE, API dates are parsed as Date values and observations are returned in wide or long format according to out_format. When extract_metadata = TRUE, it returns one row per valid series with fields returned by the Series List request, including fechaInicio, fechaFin and metadata fields derived from informacion.

Series identifiers

BdE identifies each series with a stable sequential number (Numero_secuencial) in bulk CSV files and an API series code (Nombre_de_la_serie) in the Statistics web service. bde_series_load() accepts stable sequential numbers in series_code. bde_series_api_latest() and bde_series_api_load() use the same argument for API series codes. Use bde_catalog_load() or bde_catalog_search() to find both identifiers.

See Also

• bde_catalog_load() and bde_catalog_search() help find API series codes.

• bde_series_load() loads time series from bulk CSV files.

Time series functions: bde_series

Examples

xr <- bde_catalog_load(catalog = "TC")

# Extract the latest value.
library(dplyr)
xr |>
  slice_head(n = 3) |>
  pull(Nombre_de_la_serie) |>
  bde_series_api_latest(language = "en") |>
  glimpse()

# Extract the latest months.
xr |>
  slice_head(n = 1) |>
  pull(Nombre_de_la_serie) |>
  bde_series_api_load(language = "en", time_range = "12M") |>
  glimpse()

# Extract metadata.
xr |>
  slice_head(n = 1) |>
  pull(Nombre_de_la_serie) |>
  bde_series_api_load(
    language = "en", time_range = "12M",
    extract_metadata = TRUE
  ) |>
  glimpse()

BdE color palettes

Description

Manually defined palettes based on BdE publications. Each palette contains at most six colors.

Usage

bde_tidy_palettes(
  n = 6,
  palette = c("bde_vivid_pal", "bde_rose_pal", "bde_qual_pal"),
  alpha = NULL,
  rev = FALSE
)

Arguments

Value

A character vector of hex color codes.

See Also

Plotting functions: scales_bde, theme_tidybde()

Examples

# Show the BdE vivid palette.
scales::show_col(bde_tidy_palettes(palette = "bde_vivid_pal"),
  labels = FALSE
)

# Show the BdE rose palette.
scales::show_col(bde_tidy_palettes(palette = "bde_rose_pal"),
  labels = FALSE
)

# Show the BdE qualitative palette.
scales::show_col(bde_tidy_palettes(palette = "bde_qual_pal"),
  labels = FALSE
)

Superseded BdE palettes

Description

These palettes are superseded. Use bde_tidy_palettes() instead.

Usage

bde_vivid_pal(...)

bde_rose_pal(...)

Arguments

Value

A color palette function.

Examples

# Show the vivid palette.
scales::show_col(bde_vivid_pal()(6), labels = FALSE)

# Show the rose palette.
scales::show_col(bde_rose_pal()(6), labels = FALSE)

BdE color scales

Description

Color scales for ggplot2. Discrete scales are named ⁠scale_*_bde_d⁠; continuous scales are named ⁠scale_*_bde_c⁠.

Usage

scale_color_bde_d(
  palette = c("bde_vivid_pal", "bde_rose_pal", "bde_qual_pal"),
  alpha = NULL,
  rev = FALSE,
  ...
)

scale_fill_bde_d(
  palette = c("bde_vivid_pal", "bde_rose_pal", "bde_qual_pal"),
  alpha = NULL,
  rev = FALSE,
  ...
)

scale_color_bde_c(
  palette = c("bde_rose_pal", "bde_vivid_pal", "bde_qual_pal"),
  alpha = NULL,
  rev = FALSE,
  guide = "colorbar",
  ...
)

scale_fill_bde_c(
  palette = c("bde_rose_pal", "bde_vivid_pal", "bde_qual_pal"),
  alpha = NULL,
  rev = FALSE,
  guide = "colorbar",
  ...
)

Arguments

Value

A ggplot2 scale object.

See Also

ggplot2::discrete_scale() and ggplot2::continuous_scale() for the underlying scale constructors.

Plotting functions: bde_tidy_palettes(), theme_tidybde()

Examples

library(ggplot2)

set.seed(596)
txsamp <- subset(
  txhousing,
  city %in% c(
    "Houston", "Fort Worth",
    "San Antonio", "Dallas", "Austin"
  )
)

ggplot(txsamp, aes(x = sales, y = median)) +
  geom_point(aes(colour = city)) +
  scale_color_bde_d() +
  theme_minimal()

ggplot(txsamp, aes(x = sales, y = median)) +
  geom_point(aes(colour = city)) +
  scale_color_bde_d("bde_qual_pal") +
  theme_minimal()

BdE theme for ggplot2

Description

A custom ggplot2 theme based on BdE publications.

Usage

theme_tidybde(...)

Arguments

Details

This theme extends ggplot2::theme_classic().

Value

A ggplot2 theme object.

See Also

ggplot2::theme_classic() for the base theme extended here.

Plotting functions: bde_tidy_palettes(), scales_bde

Examples

library(ggplot2)
library(dplyr)
library(tidyr)

series_TC <- bde_series_full_load("TC_1_1.csv")

# Plot if the download succeeds.
if (nrow(series_TC) > 0) {
  series_TC <- series_TC[c(1, 2)]

  series_TC_pivot <- series_TC |>
    filter(
      Date >= "2020-01-01" & Date <= "2020-12-31",
      !is.na(series_TC[[2]])
    )

  names(series_TC_pivot) <- c("x", "y")

  ggplot(series_TC_pivot, aes(x = x, y = y)) +
    geom_line(linewidth = 0.8, color = bde_tidy_palettes(n = 1)) +
    labs(
      title = "Title",
      subtitle = "Some metric",
      caption = "Banco de España"
    ) +
    theme_tidybde()
}