Banco de Mexico has developed an API for Developers, Analysts and Researchers to automatically retrieve the databases from the SIE. In this repository I share tips and tools to use this useful API with R.
# ⚠ The views and conclusions presented in this Repository are exclusively #
# the responsibility of the author and do not necessarily reflect those #
# of Banco de Mexico. #
Central Banks are some of the institutions with the best reputation in each country, with the main aims of control the Inflation, supervise the Financial Institutions, and produce and distribute Currency at a national level, among other tasks.
Banco de Mexico, founded in 1925 and autonomy since 1994, plays a key role in the Economy of the Mexico. As the Central Bank, it publishes the archive of national economic databases through the Economic Information System, known as SIE.
Additionally, this Central Bank has developed an API that allows Developers, Analysts and Researchers to consult automatically the SIE's time series, using JavaScript, Java, C# and R. More details of the API can be found in the SIE API official webpage.
The aim of this repository is to show how to use SIE's API with R, explaining how to retrieve information with the siebanxicor R package developed by Banco de Mexico, and how to use a custom function to explore the selected time series, and a Dashboard to look into Banknotes and Coins series.
As mentioned before, in this repository we will focus in how to use SIE API with R.
The first step is to get a Bmx-Token. You can request a 64-alphanumeric token in this link, which would be required to use the API.
Banco de Mexico developed the siebanxicor R package to automatically retrieve economic databases published in the SIE by Banco de Mexico. You can install it by running the next line in R or Rstudio:
install.packages("siebanxicor")
More details of siebanxicor can be found ⭐️ here.
The siebanxicor R package has five utility functions to retrieve information from the databases published by the Mexican Central Bank:
-
setToken- while the Bnx-Token is the key to access SIE API, thesetTokenfunction is the knob that opens the channel and connects to this API. This utility function should be called before any other function from the siebanxicor package. -
getSeriesData- requests the time series data from the SIE, up to 100 series at a time. It returns a vector with the requested information. -
getSeriesMetadata- retrieves metadata for the requested series. -
getSerieDataFrame- allows to get a data.frame from only one time series of the vector returned by thegetSeriesDatautility function. -
getSeriesCurrentValue- requests the time series data from the SIE, up to 100 series at a time, returning a data.frame with only the last value of the requests time series.
Note: In some cases, to use one of these functions you should previously use another(s) of the mentioned functions; for example, to use getSeriesMetadata you should previously call setToken and getSeriesData.
Additionally, I have created a custom support function that can be found in the src folder of this repo, to help Analysts and Researchers to easily explore the time series:
sie_function- when giving the names of the code of different series, it automatically prints and saves the plot of this series, prints the metadata, and returns the data in a tidy format frame format.
To complement this effort, I built a Shiny Dashboard that focus on Mexican Banknotes and Coins exploring currency time series from SIE API with the option of saving the database of the selected series, in wide or tidy format.
| R packages |
|---|
| siebanxicor |
| tidyverse |
| tidyr |
| reshape2 |
| reticulate |
| shiny |
| shinydashboard |
| shinyWidgets |
To show the usage of the SIE API with siebanxicor R package, we will go through an example using the time series for the of the Annual counterfeit domestic banknotes detected for the current denomination in circulation: 20, 50, 100, 200, 500 and 1000 pesos (series SM1249, SM1250, SM1251, SM1252, SM1253, SM1254).
⭐️ Click here to look for the complete catalogue of the SIE's time series published by Banco de Mexico.
After the siebanxicor package is installed, load this library and also the tidyverse library.
library("siebanxicor")
library("tidyverse")
Bring your token and open the SIE API channel with the setToken utility function.
# bring the token
token_file <- read.csv("../token/SIE_Token.csv", header=FALSE)
# set the token
setToken(token_file$V2)
Notes:
- If you don't have a token to use SIE API, ⭐️ click here to access the official website and obtain one.
- I add a csv file where users should paste and save their token to run this example.
Get the time series of interest, in this case the series of the annual counterfeit of mexican banknotes per denomination, using the getSeriesData function.
# setting the variables
my_series <- c("SM1249", "SM1250", "SM1251", "SM1252", "SM1253", "SM1254")
my_start <- '2015-01-01'
my_end <- Sys.Date() #looks for today's date
# getting the series
series <- getSeriesData(my_series, my_start, my_end)
Note: to use the getSeriesData function, you should previously call setToken.
This function returns the general information of series. To select the language of the metadata, set the locale variable as "en" for English, and "es" for Spanish.
# getting the metadata
metadata <- getSeriesMetadata(my_series, locale="en")
Note: to use the getSeriesMetadata function, you should previously call setToken.
This function will be helpful to get a data frame for the annual counterfeit number of 500 pesos banknotes (SM1253 series), from the vector returned by the getSerieDataFrame in the previous point #3.
# getting the series
df_SM1255 <- getSerieDataFrame(series, "SM1255")
Note: to use the getSerieDataFrame function, you should previously call setToken and getSerieData.
To get the last value of the annual counterfeit banknotes per denomination series, we will use the getSeriesCurrentValue function.
df_last_value <- getSeriesCurrentValue(my_series)
Note: to use the getSeriesCurrentValue function, you should previously call setToken.
7. Use the custom function sie_function(series_codes, series_names, title_plot, x_lab, y_lab, startDate, endDate, route)
This function prints the metadata for the Annual Counterfit Banknotes series, prints and saves and their plot, and returns a data frame with these series in tidy format.
# call the customed function from an RScript
source("SIE_function.R")
# setting the variables
my_series <- c("SM1249", "SM1250", "SM1251", "SM1252", "SM1253", "SM1254")
my_names <- c("20", "50", "100", "200", "500", "1000")
my_title <- "Annual Counterfeit Banknotes per Denomination"
my_start <- '2010-01-01'
my_end <- Sys.Date() #looks for today's date
# run the function
df <- sie_function(my_series, my_names, my_title, route="../img/",
y_lab="Number of Pieces", x_lab="Year", startDate=my_start)
In this case, the function plots the series for the Annual Counterfeit of Banknotes per denomination as follows.
⭐️ Click here to access to a complementary document developed to show additional examples of this custome function, applied to different contexts with time-series published in the SIE by Banco de Mexico.
The goal of this dashboard is to help users to easily explore time series from SIE API. In this case, the app is focus on currency series, but it could be expanded in the future.
It includes different options to select up to 10 series, in a given date range, with the possibility of changing the title and label of the plot, select a format to present the database, and a button to download the series' database in the select format.
There are different options to run this app:
-
App file: Open the file
app.Rlocated in the sie_app folder, and click on▶️ Run App. -
R project: Open the R project of this repository named as
SIE_API_guide.Rproj, and run in the console:
shiny::runApp("sie_app")- Terminal: Open the terminal and, from the main folder of this repository, run the following line:
Rscript -e 'library(methods); shiny::runApp("sie_app/", launch.browser = TRUE)'
If you use Banco de Mexico's SIE API, you must clearly state the source and include a reference to Banco de México's URL address to enable third parties to verify the information's accuracy. For more details, look into the Disclaimer shared by the Central Bank.
Additionally, the materials of this repository are of public domain. If re-using/re-mixing the material, please provide attribution and link to the repository webpage.