Package 'rwebstat'

Title: Download Data from the Webstat API
Description: Access the Webstat API, download data and metadata from more than 35000 time series from the Banque de France statistics web portal. Access requires a free client ID easily available from the API portal <https://developer.webstat.banque-france.fr/>.
Authors: Vincent Guegan [aut, cre], Etienne Kintzler [aut], Jules Lecocq [aut]
Maintainer: Vincent Guegan <[email protected]>
License: GPL-3
Version: 1.1.1
Built: 2025-02-27 03:01:04 UTC
Source: https://github.com/cran/rwebstat

Help Index

Request data from a Webstat dataset.

Description

Request data from a Webstat dataset.

Usage

w_data(
  dataset_name = NA,
  series_name = NA,
  startPeriod = NA,
  endPeriod = NA,
  firstNObs = NA,
  lastNObs = NA,
  language = "fr",
  format = "json",
  base_url = "https://api.webstat.banque-france.fr/webstat-",
  client_ID
)

Arguments

dataset_name

Optional. String (must be entered between quotes.) The datasets codes can be determined using the w_datasets() function.
series_name

Optional. String (must be entered between quotes.) The series names can be found using the w_series(dataset) function. Wildcarding is supported by replacing one (or several) dimensions by the "*" character. At least one dimension must be specified. Example: "M.USD.EUR.SP00.E" : US dollar exchange rate against the Euro, monthly Example: "*.*.EUR.SP00.E" : All available exchange rates against the Euro, all available frequencies
startPeriod

Optional. String. Start period (inclusive). ISO8601 (e.g. 2014-01) or SDMX reporting period (e.g. 2014-Q3).
endPeriod

Optional. String. End period (inclusive). ISO8601 (e.g. 2014-01-01) or SDMX reporting period (e.g. 2014-Q3).
firstNObs

Optional. String or Numeric. Maximum number of observations starting from the first observation
lastNObs

Optional. String or Numeric. Maximum number of observations counting back from the most recent observation
language

Optional. String. Defaults to "fr" (French). The only other available option is "en" (English). Determines the language of the metadata. Your Webstat "App" must be subscribed to the API in this language (or both languages) or you'll get a 501 http error.
format

Optional. String. Defaults to "json".The only other available option is "csv". The "json" option gives a better and cleaner results (POSIX dates, etc). "csv" files are smaller and could be used to request large datasets that generate timeouts. Dataframes might then have to be cleaned manually.
base_url

Optional. String. Defaults to "https://api.webstat.banque-france.fr/webstat-". For internal testing purposes only.
client_ID

Optional. String. If you do not specify it when calling the function, it will check if a global variable called "webstat_client_ID" exists and use it. If not, you will be prompted. The easiest way is to save the client ID as a string in a "webstat_client_ID" global variable.

Value

A dataframe with metadata attributes (that you can access with the w_meta() function)

Warning

A full dataset download will usually take a very long time and might time out and fail. Please use the available arguments to restrict your data selection.

Identification

You should declare your Webstat client ID in a global "webstat_client_ID" variable. Alternatively, you can enter your client ID as a parameter or enter it when prompted.

Period formats

  • Daily/Business YYYY-MM-DD

  • Monthly YYYY-MM

  • Quarterly YYYY-Q[1-4]

  • Annual YYYY

Examples

## Not run: 
## Request the US Dollar monthly exchange rates in Euro
w_data(dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E")
or
w_data("EXR.M.USD.EUR.SP00.E")

## Request the US Dollar monthly exchange rates in Euro, from May 2017 to April 2018
w_data(
  dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E",
  startPeriod = "2017-05", endPeriod = "2018-04"
)

## Request the three last values of the US Dollar monthly exchange rates in Euro with
## all metadata in English
w_data(dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E", lastNObs = 3, language = "en")

## Use wildcards : request all available monthly exchange rates in Euro
## (at least one dimension must be specified)
w_data(dataset_name = "EXR", series_name = "M.*.EUR.SP00.E")

## Request more than one serie
w_data("EXR", series_name = "D.DKK.EUR.SP00.A+D.GBP.EUR.SP00.A+M.USD.EUR.SP00.A+M.USD.EUR.SP00.E")

## Request all series of a dataset
w_data("CPP")

## Access metadata of the US Dollar monthly exchange rates
df <- w_data(dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E")
meta <- w_meta(df)

## Your client ID can be entered as a parameter as follows or saved
## in a global variable named "webstat_client_ID" in order to reuse it.
w_data("CPP", client_ID = "1234abcd-12ab-12ab-12ab-123456abcdef")

## End(Not run)

List all the available datasets from Webstat (codes and names) in a table. No arguments.

Description

List all the available datasets from Webstat (codes and names) in a table. No arguments.

Usage

w_datasets(
  language = "fr",
  base_url = "https://api.webstat.banque-france.fr/webstat-",
  client_ID
)

Arguments

language

Optional. String. Defaults to "fr" (French). The only other available option is "en" (English). Determines the language of the metadata. Your Webstat "App" must be subscribed to the API in this language or you'll get a 501 http error.
base_url

Optional. String. Defaults to "https://api.webstat.banque-france.fr/webstat-". For internal testing purposes only.
client_ID

Optional. String. If you do not specify it when calling the function, it will check if a global variable called ".GlobalEnv$webstat_client_ID exists and use it. If not, you will be prompted. The easiest way is to save the client ID as a string in ".GlobalEnv$webstat_client_ID".

Value

A data frame containing the dataset codes and datasets names

Identification

You should declare your Webstat client ID in a global "webstat_client_ID" variable. Alternatively, you can enter your client ID as a parameter or enter it when prompted.

Examples

## Not run: 
## Request the dataset catalogue
w_datasets()

## Request the dataset catalogue, in English
w_datasets(language = "en")

## Your client ID can be entered as a parameter as follows or saved
## in a global variable named "webstat_client_ID" in order to reuse it.
w_datasets(client_ID = "1234abcd-12ab-12ab-12ab-123456abcdef")

## End(Not run)

Get metadata from a dataframe returned by w_data function

Description

Get metadata from a dataframe returned by w_data function

Usage

w_meta(data)

Arguments

data

dataframe from w_data()

Value

dataframe

Examples

## Not run: 
## Request the US Dollar monthly exchange rates in Euro
df <- w_data(dataset_name = "EXR", series_name = "M.USD.EUR.SP00.E")
meta <- w_meta(df)

## End(Not run)

Search keyword inside dataset catalogue or series catalogue

Description

Search keyword inside dataset catalogue or series catalogue

Usage

w_search(
  dataset_name,
  keyword = "",
  language = "fr",
  client_ID,
  base_url = "https://api.webstat.banque-france.fr/webstat-",
  ignore.case = TRUE,
  fixed = FALSE,
  ...
)

Arguments

dataset_name

Optional. String (must be entered between quotes.) The datasets codes can be determined using the w_datasets() function.
keyword

Optional. String or regexp you want to search
language

Optional. String. Defaults to "fr" (French). The only other available option is "en" (English). Determines the language of the metadata. Your Webstat "App" must be subscribed to the API in this language (or both languages) or you'll get a 501 http error.
client_ID

Optional. String. If you do not specify it when calling the function, it will check if a global variable called "webstat_client_ID" exists and use it. If not, you will be prompted. The easiest way is to save the client ID as a string in a "webstat_client_ID" global variable.
base_url

Optional. String. Defaults to "https://api.webstat.banque-france.fr/webstat-". For internal testing purposes only.
ignore.case

Optional. Boolean. Break case sensitivity
fixed

Optional. Boolean. Allow or not regexp expressions
...

Arguments to be passed to grepl function ("fixed = TRUE" if you don't want to use regexp)

Value

A dataframe

Examples

## Not run: 
# find Danish exchange rate code series (fr & en) :
w_search("EXR", keyword = "danoise", fixed = TRUE)
w_search("EXR", keyword = "Danish", fixed = TRUE, language = "en")

# find datasets with keyword :
w_search(keyword = "Emploi", fixed = TRUE)
w_search(keyword = "Interest Rates", language = "en", fixed = TRUE)

# regexp can also be used - find series starting with "Monetary"
w_search(keyword = "^Monetary", language = "en")

## End(Not run)

List the available series from a dataset.

Description

List the available series from a dataset.

Usage

w_series_list(
  dataset_name,
  language = "fr",
  client_ID,
  base_url = "https://api.webstat.banque-france.fr/webstat-"
)

Arguments

dataset_name

Mandatory. String (Must be between quotes.) The datasets codes can be determined with the w_datasets() function.
language

Optional. String. Defaults to "fr" (French). The only other available option is "en" (English). Determines the language of the metadata. Your Webstat "App" must be subscribed to the API in this language (or both) or you'll get a 501 http error.
client_ID

Optional. String. If you do not specify it when calling the function, it will check if a global variable called ".GlobalEnv$webstat_client_ID exists and use it. If not, you will be prompted. The easiest way is to save the client ID as a string in ".GlobalEnv$webstat_client_ID".
base_url

Optional. String. Defaults to "https://api.webstat.banque-france.fr/webstat-". For internal testing purposes only.

Value

A data frame listing all the series from the requested dataset with their codes, titles and dimensions.

Identification

You should declare your Webstat client ID in a global "webstat_client_ID" variable. Alternatively, you can enter your client ID as a parameter or enter it when prompted.

Examples

## Not run: 
## Request the list of all series from the BPM6 dataset
w_series_list("BPM6")

## Request the list of all series from the CPP dataset, with English metadata
w_series_list("CPP", language = "en")

## Your client ID can be entered as a parameter as follows or saved
## in a global variable named "webstat_client_ID" in order to reuse it.
w_series_list("CPP", client_ID = "1234abcd-12ab-12ab-12ab-123456abcdef")

## End(Not run)

Get the structure of a dataset

Description

Get the structure of a dataset

Usage

w_structure(
  dataset_name,
  language = "fr",
  option = "light",
  client_ID,
  base_url = "https://api.webstat.banque-france.fr/webstat-"
)

Arguments

dataset_name

Mandatory. String (must be entered between quotes.) The datasets codes can be determined using the w_datasets() function.
language

Optional. String. Defaults to "fr" (French). The only other available option is "en" (English). Determines the language of the metadata. Your Webstat "App" must be subscribed to the API in this language or you'll get a 501 http error.
option

Optional. 'light' or 'full'
client_ID

Optional. String. If you do not specify it when calling the function, it will check if a global variable called "webstat_client_ID" exists and use it. If not, you will be prompted. The easiest way is to save the client ID as a string in a "webstat_client_ID" global variable.
base_url

Optional. String. Defaults to "https://api.webstat.banque-france.fr/webstat-". For internal testing purposes only.

Value

a list of dataset structure

Examples

## Not run: 
w_structure("EXR")

## End(Not run)