package R : rwebstat

Banque de France Jules Lecocq & Vincent Guegan

2023-06-06

## Warning: The `path` argument of `write_lines()` is deprecated as of readr 1.4.0.
## ℹ Please use the `file` argument instead.
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.

Introduction

The rwebstat package was created to facilitate access to the webstat API. All the data are available on Webstat, the official external data provider website of Banque de France.

The first version was published on CRAN 2019-05-24.

Requirement

The first step is to register on the API at link.

You can find operating procedure at these links ( fr and en )

Once done, you have to login and create an App which will give you an API key (personal Client ID).

There are multiple ways to enter your API key. The simpler one is to store it in a global variable named “webstat_client_api” :

webstat_client_ID <- "3141592-65359-26535"

If you forget to create the variable, don’t worry, the first function call will prompt you to enter it into RStudio Console.

Proxy issues

**Requirement for Banque of France employees**

To use efficiently rwebstat inside the Bank domain, you have to set your proxy with the proxy_bdf() function. Just enter your password when prompted.

proxy_bdf()

In any case, you need to set your proxy parameters (if you have any) in order to request the Webstat API.

Installation

You can easily install rwebstat with the following code :

install.packages("rwebstat")

Functionalities

This section will give you an overview of what you can do with rwebstat.

Data are stored in Series (time series). Series are stored in Datasets.

Series id are Series keys (sdmx format). Datasets id are strings.

Catalogues

We can easily recover Datasets and Series catalogues :

Datasets

Webstat offers more than 40 Datasets. The w_datasets() function returns the datasets catalogue :

datasets <- w_datasets("en") # function call

Series

Webstat corrently offers more than 40.000 Series. The w_series_list() function returns the series catalogue.

For example, we ask the EXR dataset catalogue (only top rows are displayed here) :

EXR_series <- w_series_list("EXR") # function call

Download data

Download all Series of a specific Dataset or an individual Serie with w_data() function :

CPP_series_data <- w_data("CPP") # CPP is the smallest Dataset - 2 Series only

Download a specific Serie (series_name and dataset_name arguments are flexible) :

USD_EUR <- w_data(dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E") # exchange rate USD/EUR
USD_EUR <- w_data("EXR.M.USD.EUR.SP00.E")

We don’t always know the exact Serie(s) key(s) we want to request. The w_search() function search keyword (regexp are accepted) inside catalogues.

Datasets

For example, we look for the keyword “monetary” into the Dataset catalogue :

s1 <- w_search(keyword="monetary",language="en")

The keyword argument can be written in a regexp form to be more efficient.

s2 <- w_search(keyword="\\wary",language="en") # use regexp to capture everything finising with "ary"

Series

We can pass all arguments from the grep() function family. If we don’t want to search for a regexp expression, we pass the argument fixed=TRUE.

For example, we look for the exact word “dollar” into the EXR Series catalogue :

s3 <- w_search("EXR",keyword="dollar",fixed=TRUE)

Metadata and structure

Metadata

The w_meta() function return metadatas of a Serie. The language of the metadata will be the same as the language chosen for the Serie :

USD_EUR <- w_data("EXR.M.USD.EUR.SP00.E",language="fr")
USD_EUR_meta <- w_meta(USD_EUR)
USD_EUR <- w_data("EXR.M.USD.EUR.SP00.E",language="en")
USD_EUR_meta <- w_meta(USD_EUR)

Structure

The w_structure() function returns information on the structure of a specific Dataset as a R list :

EXR_STRUCT <- w_structure("EXR",language="en")
class(EXR_STRUCT)

Elements of the structure list :

names(EXR_STRUCT)

A Serie key (SDMX format) is a chain of strings separated with dots (M.USD.EUR.SP00.E). Each string is a dimension,

Dimensions of a Serie key from the EXR Dataset :

EXR_STRUCT_dimensions <- EXR_STRUCT$keyFamily$dimensions[,1]

Useful examples

We want to get back the last values of all Exchange rates Series (EXR Dataset) involving a “dollar” currency.

First we search the EXR Dataset for all the Series containing the “dollar” keyword :

Series_dollar <- w_search("EXR",keyword="dollar",language="fr",fixed=TRUE)
dim(Series_dollar)

We have a list of 24 Series :

Series <- Series_dollar$SeriesKey

We then apply the w_data() function to the SeriesKey vector we found in the search :

Series_Data_list <-  lapply(Series,w_data)

Support

Feel free to contact us with any question about the API or this package using this e-mail address.