package R : rwebstat

Banque de France

Jules Lecocq & Vincent Guegan

2020-04-10

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
Name Description Last_Update
STS Short-Term Statistics 2020-03-19 13:48:43
SC1 Securities - France 2020-04-10 09:56:37
DIREN Companies 2020-04-10 10:27:46
MIR1 Interest Rates - France 2020-04-10 10:27:46
CPP Commercial Property Price 2020-03-04 19:00:22
CFT Quarterly financial accounts 2020-03-04 19:10:37
FM Financial Market Data 2020-04-10 10:27:46
CONJ2 Short-Term Surveys Regional 2020-03-16 14:02:13
SA Cptes nationaux SA 2020-03-04 20:34:17
MIR Interest Rates - Euro area 2020-04-09 11:02:51
MNA National Accounts Main Aggregates 2020-03-04 19:23:55
CONJ Short-Term Surveys National 2020-04-10 10:27:46
IVF1 Investment Funds 2020-03-18 10:24:43
ESTR Euro short-term rate - €STR 2020-04-09 08:31:35
FCI Banque de France Financial Conditions Index (BdF FCI) 2020-03-04 19:00:22
ECOFI ECOFIN : Economy and Finance 2020-04-09 11:17:51
AME Macro Economy - Euro Area 2020-03-04 19:32:16
CDIS Direct Investments - CDIS - SDDS 2020-03-04 19:15:37
CFANF financial accounts of non financial companies 2020-03-04 19:23:55
CFTDC CEFIT : Loans and Deposits in French Regions 2020-03-23 11:34:36
BPM6 Balance of payments- 6th manual 2020-04-07 09:04:42
CNF Financial National Accounts 2020-03-04 20:53:58
EXR Exchange Rates 2020-04-10 10:15:13
ICP Indexes of Consumer Price 2020-03-19 14:26:01
FATSO FATS Outwards 2020-03-04 19:23:55
SEC Securities - Euro area 2020-03-12 10:18:37
FTID Quarterly Direct Investments 2020-03-31 11:29:37
ESA ESA95 National Accounts 2020-03-04 19:32:16
OFC Other financial corporations survey 2020-03-04 19:10:37
BLS Bank Lending Survey 2020-04-10 09:56:37
CEFIT Loans and Deposits in French Regions 2020-03-23 11:27:56
QFAGG Quarterly financial accounts of general government 2020-03-04 19:00:22
SAFE Access to Finance of SMEs 2020-04-10 10:27:46
TCN2 Marketable Date Instruments - TCN2 2020-04-09 11:32:52
DSE Debt Titles 2020-04-10 08:41:16
BSI Monetary Statistics - Euro Area 2020-04-02 17:28:18
ENDET National Accounts - Indebtness 2020-03-04 20:11:05
PME Finance of SMEs 2020-04-10 09:56:37
ICB Insurance corporations assets and liabilities 2020-03-04 20:53:58
RA_T Reserve assets template 2020-04-07 12:21:46
RPP Residential Property Price 2020-03-04 19:23:55
GST Government Statistics 2020-03-04 20:19:17
DET Holdings by non-residents 2020-03-26 09:47:51
CONS Securities Holding 2020-03-27 12:28:21
BSI1 Monetary Statistics - France 2020-04-09 11:02:51

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
SeriesKey Title TitleCompl ExtTitle NatTitle SourceAgency From To FREQ CURRENCY CURRENCY_DENOM EXR_TYPE EXR_SUFFIX
EXR.M.DKK.EUR.SP00.A Couronne danoise (DKK) Cours de change de l’euro contre couronne danoise (DKK) - source BCE (14:15 CET) Danish krone (DKK) ECB reference exchange rate, Danish krone/Euro, 2:15 pm (C.E.T.) 4F0 01/01/1999 01/03/2020 M DKK EUR SP00 A
EXR.M.DKK.EUR.SP00.E Cours de change de l’euro contre couronne danoise (DKK) - fin de mois ECB reference exchange rate, Danish krone/Euro, 2:15 pm (C.E.T.), end-of-period ECB reference exchange rate, Danish krone/Euro, 2:15 pm (C.E.T.) 4F0 01/01/1999 01/03/2020 M DKK EUR SP00 E
EXR.M.GBP.EUR.SP00.A Livre sterling (GBP) Cours de change de l’euro contre livre sterling (GBP) - source BCE (14:15 CET) UK pound sterling (GBP) ECB reference exchange rate, UK pound sterling/Euro, 215 pm (C.E.T.) 4F0 01/01/1999 01/03/2020 M GBP EUR SP00 A
EXR.M.GBP.EUR.SP00.E Cours de change de l’euro contre livre sterling (GBP) - fin de mois ECB reference exchange rate, UK pound sterling/Euro, 2:15 pm (C.E.T.), end-of-period ECB reference exchange rate, UK pound sterling/Euro, 215 pm (C.E.T.) 4F0 01/01/1999 01/03/2020 M GBP EUR SP00 E
EXR.M.HKD.EUR.SP00.A Dollar de Hong Kong (HKD) Cours de change de l’euro contre dollar de Hong Kong (HKD) - source BCE (14:15 CET) Hong Kong dollar (HKD) ECB reference exchange rate, Hong Kong dollar/Euro, 2:15 pm (C.E.T.) 4F0 01/01/1999 01/03/2020 M HKD EUR SP00 A

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
date CPP.A.FR.N.TH.TVAL.TP.5.ANR CPP.Q.FR.N.TH.TVAL.TP.5.ANR
2016-01-01 7.8 NA
2017-01-01 8.1 2.1
2017-04-01 NA 5.4
2017-07-01 NA 10.0
2017-10-01 NA 14.7
2018-01-01 NA 6.7
2018-04-01 NA 3.1
2018-07-01 NA -0.5

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")
date EXR.M.USD.EUR.SP00.E
1999-01-01 1.1384
1999-02-01 1.1018
1999-03-01 1.0742
1999-04-01 1.0597
1999-05-01 1.0456
1999-06-01 1.0328
1999-07-01 1.0694
1999-08-01 1.0573
1999-09-01 1.0665
1999-10-01 1.0453

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)
Metadata EXR.M.USD.EUR.SP00.E
dataset_name EXR
title Cours de change de l’euro contre dollar des Etats-Unis (USD) - fin de mois
freq M
titleCompl Cours de change de l’euro contre dollar des Etats-Unis (USD) - fin de mois 
USD_EUR <- w_data("EXR.M.USD.EUR.SP00.E",language="en")
USD_EUR_meta <- w_meta(USD_EUR)
Metadata EXR.M.USD.EUR.SP00.E
dataset_name EXR
title ECB reference exchange rate, US dollar/Euro, 2:15 pm (C.E.T.)
freq M
titleCompl ECB reference exchange rate, US dollar/Euro, 2:15 pm (C.E.T.)

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)
## [1] "list"

Elements of the structure list :

names(EXR_STRUCT)
## [1] "id"                        "name"                     
## [3] "description"               "hasTitle"                 
## [5] "defaultSortDimensionId"    "defaultSortDimensionOrder"
## [7] "defaultArea"               "isoA2"                    
## [9] "keyFamily"

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]
key name position dimensionValues filter
FREQ Frequency 1 NULL FALSE
CURRENCY Currency 2 NULL TRUE
CURRENCY_DENOM Currency denominator 3 NULL FALSE
EXR_TYPE Exchange rate type 4 NULL FALSE
EXR_SUFFIX Series variation - EXR context 5 NULL TRUE

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)
## [1] 24 13

We have a list of 24 Series :

Series <- Series_dollar$SeriesKey
Series_dollar.SeriesKey Series_dollar.Title
EXR.M.HKD.EUR.SP00.A Dollar de Hong Kong (HKD)
EXR.M.HKD.EUR.SP00.E
EXR.M.NZD.EUR.SP00.A Dollar neo-zélandais (NZD)
EXR.M.NZD.EUR.SP00.E
EXR.D.USD.XGO.SP00.E Cours de l’or contre dollar - 1er fixing à Londres
EXR.M.BND.EUR.SP00.E
EXR.M.SGD.EUR.SP00.A Dollar de Singapour (SGD)
EXR.M.SGD.EUR.SP00.E
EXR.M.USD.EUR.SP00.A Dollar des Etats-Unis (USD)
EXR.M.USD.EUR.SP00.E
EXR.M.TWD.EUR.SP00.E
EXR.M.XCD.EUR.SP00.E
EXR.M.ZWL.EUR.SP00.E
EXR.M.KYD.EUR.SP00.E
EXR.M.AUD.EUR.SP00.A Dollar australien (AUD)
EXR.M.AUD.EUR.SP00.E
EXR.M.CAD.EUR.SP00.A Dollar canadien (CAD)
EXR.M.CAD.EUR.SP00.E
EXR.D.CAD.EUR.SP00.A Dollar canadien (CAD)
EXR.D.HKD.EUR.SP00.A Dollar de Hong Kong (HKD)
EXR.D.AUD.EUR.SP00.A Dollar australien (AUD)
EXR.D.NZD.EUR.SP00.A Dollar neo-zélandais (NZD)
EXR.D.SGD.EUR.SP00.A Dollar de Singapour (SGD)
EXR.D.USD.EUR.SP00.A Dollar des Etats-Unis (USD)

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.