package R : rwebstat"

In rwebstat: Download Data from the Webstat API

# setup chunk
NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")),"true")
knitr::opts_chunk$set(purl = NOT_CRAN)
library(rwebstat)

library(kableExtra)
library(magrittr)
library(htmltools)
library(prettydoc)

if (require(htmltools)) {
img <- htmltools::img(src = knitr::image_uri("logo_webstat.png"),
               alt = 'logo',
               style = 'position:absolute; top:0; right:0; padding:10px;')

img_0 <- htmltools::img(src = knitr::image_uri("Nouveau_logo_Banque_de_France.jpg"),
               alt = 'logo',
               style = 'position:absolute; top:0; left:0; padding:10px',
               width = '180px',
               height = '85px;')

htmlhead <- paste0('
<script>
document.write(\'<div class="logos">',img,img_0,'</div>\')
</script>
')

readr::write_lines(htmlhead, path = "header.html") }

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"

webstat_client_ID <- "300b933e-896f-4be2-b474-769894a56605"

proxy_bdf()

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

rownames(datasets) <- NULL
datasets %>% 
        kable(row.names=NA) %>% 
        kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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

rownames(EXR_series) <- NULL
EXR_series %>% 
          head(5) %>%
          kable(row.names=NA) %>% 
          kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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

rownames(CPP_series_data) <- NULL
CPP_series_data %>% 
                head(10) %>%
                kable(row.names=NA) %>% 
                kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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")

rownames(USD_EUR) <- NULL
USD_EUR %>% 
        head(10) %>%
        kable(row.names=NA) %>% 
        kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

Search

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")

rownames(s1) <- NULL
s1 %>% 
  head(5) %>%
  kable(row.names=NA) %>% 
  kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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"

rownames(s2) <- NULL
s2 %>% 
  head(5) %>%
  kable(row.names=NA) %>% 
  kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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)

rownames(s3) <- NULL
s3 %>% 
   head(5) %>%
   kable(row.names=NA) %>% 
   kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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)

rownames(USD_EUR_meta) <- NULL
USD_EUR_meta %>% 
                kable(row.names=NA) %>% 
                kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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

rownames(USD_EUR_meta) <- NULL
USD_EUR_meta %>% 
                kable(row.names=NA) %>% 
                kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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]

rownames(EXR_STRUCT_dimensions) <- NULL
EXR_STRUCT_dimensions %>% 
                      kable(row.names=NA) %>%
                      kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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)

len <- 24

len <- dim(Series_dollar)[1]

We have a list of r len Series :

Series <- Series_dollar$SeriesKey

rownames(Series) <- NULL
Series_p = data.frame(Series_dollar$SeriesKey,Series_dollar$Title)
Series_p %>% 
          kable(row.names=NA) %>%
          kable_styling(bootstrap_options = c("striped", "hover", "condensed"))

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.

rwebstat documentation built on June 7, 2023, 5:10 p.m.