In emraher/cbRt: R Interface to EDDS of CBRT

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)

cbRt

Disclaimer

This software is in no way affiliated, endorsed, or approved by the CBRT. It comes with absolutely no warranty. Also see the Disclaimer on CBRT webpage since it mentions; "Information published in this site may be quoted by specific reference thereto, but the use of such information for commercial purposes shall be subject to prior written permission of the CBRT."

Overview

cbRt is an R interface to The Electronic Data Delivery System (EDDS) of Central Bank of the Republic of Turkey (CBRT). "The system provides a rich range of economic data and information to support economic education and foster economic research."^[1]

Similar Packages

• See etaymaz/CBRT

Installation

You can install cbRt from github with:

# install.packages("devtools")
devtools::install_github("emraher/cbRt")

Usage and Arguments

There are two functions in the package.

cbrt_meta retrieves all information for all series.

series_meta_info <- cbrt_meta(token = NULL)

For token argument see the definition below. This returns a tibble. One can search this tibble to find series IDs and other information on series.

The other function is cbrt_get which retrieves data from EDDS.

cbrt_get(series, start_date, end_date, formulas, token = NULL, nd = TRUE,
         as = c("tibble", "tsibble", "data.frame", "data.table"))

Following are the arguments used in the functions. Descriptions are taken from EDDS Web Service Usage Guide.

Note that, series, start_date, end_date, and token are all required arguments.

series

series argument can be obtained from CBRT webpage. Search CBRT webpage in order to find out the series code and use it in the series argument. For example, TP.DK.USD.A is the code for (USDTRY) US Dollar (Buying) Exchange Rate.

One can also use cbrt_meta function to get all information for all series and search in the resulting tibble.

Argument can take multiple values.

start_date

start_date argument is the series start date as dd-mm-yyyy format. This argument takes a single value.

end_date

end_date argument is the series end date as dd-mm-yyyy format. This argument takes a single value.

formulas

formulas argument is the formula applied to series. Available formulas are;

• 0: Level
• 1: Percentage Change
• 2: Difference
• 3: Year-to-year Percent Change
• 4: Year-to-year Differences
• 5: Percentage Change Compared to End-of-Previous Year
• 6: Difference Compared to End-of-Previous Year
• 7: Moving Average
• 8: Moving Sum

If this parameter is not supplied by the user, the level formula parameter is applied for the relevant series. If retrieving multiple series, argument should take multiple values.

token

token argument is the required API key. Follow the instructions on CBRT webpage to obtain the user specific API key. This argument takes a single value.

You can set your token with

Sys.setenv(EVDS_TOKEN = "Iq83AIL5bss")

or you can add it to your .Renviron file as

EVDS_TOKEN = "Iq83AIL5bss"

nd

nd argument is a TRUE or FALSE argument. Data retrieved sometimes includes ND terms. If nd is set to TRUE (which is default), all NDs are converted to NAs.

as

as argument is the class of the output. Available classes are;

• tibble
• tsibble
• data.frame
• data.table

tibble is the default output class.

Examples

Single Series

Following example retrieves (USDTRY) US Dollar (Buying) Exchange Rate.

library(cbRt)
series    <- "TP.DK.USD.A"
start_date <- "01-01-2017"
end_date   <- "01-01-2018"
token     <- Sys.getenv("EVDS_TOKEN")

(usd_try <- cbrt_get(series, start_date, end_date, token = token))

Multiple Series

Following example retrieves multiple different series with different frequencies.

EDDS API converts series to a common frequency if they are requested together and no frequency argument is given.

For example, if you request one yearly and one monthly series, API will return both series as yearly values.

Package, on the other hand, sends independent queries for each series and joins them together without changing the frequency.

I opted not to include freq argument to function call.

The example below also shows the usage of the formulas argument.

start_date <- "01-01-2017"
end_date <- "01-01-2020"
series <- c("TP.AB.B1", "TP.AB.C2", "TP.BKEA.S001", "TP.KB.O06.TRL")
formulas <- c(2, 3, 7, 8)
token <- Sys.getenv("EVDS_TOKEN") # Get token from .Renviron

# data(cbrt_meta_data)
# cbrt_meta_data %>% 
#   dplyr::filter(SERIE_CODE %in% series) %>% 
#   dplyr::select(SERIE_CODE, FREQUENCY_STR)
# 
#      SERIE_CODE  FREQUENCY_STR
# 1      TP.AB.C2 HAFTALIK(CUMA)
# 2      TP.AB.B1          AYLIK
# 3  TP.BKEA.S001       ÜÇ AYLIK
# 4 TP.KB.O06.TRL         YILLIK

# EDDS API returns following
url <- paste0("https://evds2.tcmb.gov.tr/service/evds/series=TP.AB.B1-TP.AB.C2-TP.BKEA.S001-TP.KB.O06.TRL&startDate=01-01-2017&endDate=01-01-2020&type=json", "&formulas=2-3-7-8")

(edds_dat <- cbRt:::cbrt_geturl(url, token = token) %>%
    httr::content(as = "text", encoding = "UTF-8") %>% 
    jsonlite::fromJSON() %>%
    .[["items"]] %>%
    tibble::as_tibble())

NOTE that API call returns empty columns. cbrt_get function also removes them.

(dat <- cbrt_get(series, start_date, end_date, as = "tsibble"))

Series with Location Data

Following are examples for data with location attributes. Series is Hedonic House Price Index (HHPI)(2010=100)(CBRT)(Monthly). TP.HKFE02 and TP.HKFE03 are price indices codes for Istanbul and Ankara, respectively. This series can be used to draw maps. At this time there is no support in the package though.

# Single Series
series <- "TP.HKFE02"
(hhpi <- cbrt_get(series, start_date, end_date))

# Multiple Series
series <- c("TP.HKFE02", "TP.HKFE03")
(hhpi <- cbrt_get(series, start_date, end_date))

emraher/cbRt documentation built on July 14, 2024, 5:45 p.m.