Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wilsonfreitas/rbcb
R interface to Brazilian Central Bank web services
https://github.com/wilsonfreitas/rbcb
brazilian-data central-bank central-banking cross-currency-rates currency-rates download-currency-rates exchange-rate financial-data r rstats time-series
Last synced: about 2 months ago
JSON representation
R interface to Brazilian Central Bank web services
- Host: GitHub
- URL: https://github.com/wilsonfreitas/rbcb
- Owner: wilsonfreitas
- License: other
- Created: 2016-12-12T09:47:39.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-01-23T08:03:25.000Z (11 months ago)
- Last Synced: 2024-09-29T14:16:11.419Z (3 months ago)
- Topics: brazilian-data, central-bank, central-banking, cross-currency-rates, currency-rates, download-currency-rates, exchange-rate, financial-data, r, rstats, time-series
- Language: R
- Homepage: https://wilsonfreitas.github.io/rbcb/
- Size: 4.34 MB
- Stars: 90
- Watchers: 14
- Forks: 20
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-quant - rbcb - R interface to Brazilian Central Bank web services. (R / Data Sources)
README
# rbcb 
[](https://cran.r-project.org/package=rbcb)
[](https://cran.r-project.org/package=rbcb)
[](https://github.com/wilsonfreitas/rbcb/actions/workflows/check-standard.yaml)
[](https://app.codecov.io/gh/wilsonfreitas/rbcb?branch=master)
An interface to structure the information provided by the [Brazilian
Central Bank](https://www.bcb.gov.br). This package interfaces the
[Brazilian Central Bank web services](https://dadosabertos.bcb.gov.br)
to provide data already formatted into R’s data structures.
## Install
From CRAN:
``` r
install.packages("rbcb")
```
From github using remotes:
``` r
remotes::install_github('wilsonfreitas/rbcb')
```
## Features
- [rbcb](#rbcb)
- [Install](#install)
- [Features](#features)
- [Usage](#usage)
- [The `get_series` function](#the-get_series-function)
- [Market expectations](#market-expectations)
- [OLINDA API for currency
rates](#olinda-api-for-currency-rates)
- [Currency rates](#currency-rates)
- [Cross currency rates](#cross-currency-rates)
### Usage
Load the package:
``` r
library(rbcb)
```
#### The `get_series` function
Download the series by calling
`rbcb::get_series` and pass the time series code is as the first
argument. For example, let’s download the USDBRL time series which code
is `1`.
``` r
rbcb::get_series(c(USDBRL = 1))
#> # A tibble: 9,434 x 2
#> date USDBRL
#>
#> 1 1984-11-28 2828
#> 2 1984-11-29 2828
#> 3 1984-11-30 2881
#> 4 1984-12-03 2881
#> 5 1984-12-04 2881
#> 6 1984-12-05 2923
#> 7 1984-12-06 2923
#> 8 1984-12-07 2923
#> 9 1984-12-10 2965
#> 10 1984-12-11 2965
#> # ... with 9,424 more rows
```
Note that this series starts at 1984 and has approximately 8000 rows.
Also note that you can name the downloaded series by passing a named
`vector` in the `code` argument. To download recent values you should
use the argument `last = N`, see below.
``` r
rbcb::get_series(c(USDBRL = 1), last = 10)
#> # A tibble: 10 x 2
#> date USDBRL
#>
#> 1 2022-07-12 5.41
#> 2 2022-07-13 5.40
#> 3 2022-07-14 5.46
#> 4 2022-07-15 5.40
#> 5 2022-07-18 5.37
#> 6 2022-07-19 5.39
#> 7 2022-07-20 5.43
#> 8 2022-07-21 5.48
#> 9 2022-07-22 5.45
#> 10 2022-07-25 5.41
```
The series can be downloaded in many
different types: `tibble`, `xts`, `ts` or `data.frame`, but the default
is `tibble`. See the next example where the Brazilian Broad Consumer
Price Index (IPCA) is downloaded as `xts` object.
``` r
rbcb::get_series(c(IPCA = 433), last = 12, as = "xts")
#> IPCA
#> 2021-07-01 0.96
#> 2021-08-01 0.87
#> 2021-09-01 1.16
#> 2021-10-01 1.25
#> 2021-11-01 0.95
#> 2021-12-01 0.73
#> 2022-01-01 0.54
#> 2022-02-01 1.01
#> 2022-03-01 1.62
#> 2022-04-01 1.06
#> 2022-05-01 0.47
#> 2022-06-01 0.67
```
or as a `ts` object.
``` r
rbcb::get_series(c(IPCA = 433), last = 12, as = "ts")
#> Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
#> 2021 0.96 0.87 1.16 1.25 0.95 0.73
#> 2022 0.54 1.01 1.62 1.06 0.47 0.67
```
Multiple series can be downloaded at once
by passing a named vector with the series codes. The return is a named
list with the downloaded series.
``` r
rbcb::get_series(c(IPCA = 433, IGPM = 189), last = 12, as = "ts")
#> $IPCA
#> Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
#> 2021 0.96 0.87 1.16 1.25 0.95 0.73
#> 2022 0.54 1.01 1.62 1.06 0.47 0.67
#>
#> $IGPM
#> Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
#> 2021 0.78 0.66 -0.64 0.64 0.02 0.87
#> 2022 1.82 1.83 1.74 1.41 0.52 0.59
```
#### Market expectations
The function
`get_market_expectations` returns market expectations discussed in the
Focus Report that summarizes the statistics calculated from expectations
collected from market practitioners.
The first argument `type` accepts the following values:
- `annual`: annual expectations
- `quarterly`: quarterly expectations
- `monthly`: monthly expectations
- `top5s-monthly`: monthly expectations for top 5 indicators
- `top5s-annual`: annual expectations for top 5 indicators
- `inflation-12-months`: inflation expectations for the next 12 months
- `institutions`: market expectations informed by financial
institutions
The example below shows how to download IPCA’s monthly expectations.
``` r
rbcb::get_market_expectations("monthly", "IPCA", end_date = "2018-01-31", `$top` = 5)
#> # A tibble: 5 x 10
#> Indicador Data DataReferencia Media Mediana DesvioPadrao Minimo Maximo numeroRespondentes baseCalculo
#>
#> 1 IPCA 2018-01-31 06/2019 0.21 0.2 0.07 0.13 0.36 14 1
#> 2 IPCA 2018-01-31 06/2019 0.2 0.2 0.1 -0.3 0.36 43 0
#> 3 IPCA 2018-01-31 05/2019 0.31 0.29 0.06 0.22 0.43 19 1
#> 4 IPCA 2018-01-31 05/2019 0.31 0.3 0.06 0.15 0.45 55 0
#> 5 IPCA 2018-01-31 04/2019 0.38 0.39 0.1 0.16 0.61 20 1
```
#### OLINDA API for currency rates
Use currency functions to download
currency rates from the BCB OLINDA API.
``` r
olinda_list_currencies()
#> symbol name currency_type
#> 1 AUD Dólar australiano B
#> 2 CAD Dólar canadense A
#> 3 CHF Franco suíço A
#> 4 DKK Coroa dinamarquesa A
#> 5 EUR Euro B
#> 6 GBP Libra Esterlina B
#> 7 JPY Iene A
#> 8 NOK Coroa norueguesa A
#> 9 SEK Coroa sueca A
#> 10 USD Dólar dos Estados Unidos A
```
Use `olinda_get_currency` function to download data from specific
currency by the currency symbol.
``` r
olinda_get_currency("USD", "2017-03-01", "2017-03-03")
#> # A tibble: 13 x 3
#> datetime bid ask
#>
#> 1 2017-03-01 14:37:41 3.10 3.10
#> 2 2017-03-01 15:37:01 3.10 3.10
#> 3 2017-03-01 15:37:01 3.10 3.10
#> 4 2017-03-02 10:04:33 3.11 3.11
#> 5 2017-03-02 11:07:36 3.10 3.10
#> 6 2017-03-02 12:10:41 3.12 3.12
#> 7 2017-03-02 13:06:27 3.12 3.12
#> 8 2017-03-02 13:06:27 3.11 3.11
#> 9 2017-03-03 10:10:38 3.13 3.13
#> 10 2017-03-03 11:10:48 3.13 3.13
#> 11 2017-03-03 12:07:35 3.14 3.14
#> 12 2017-03-03 13:07:10 3.14 3.14
#> 13 2017-03-03 13:07:10 3.14 3.14
```
The rates come quoted in BRL, so 3.10 is worth 1 USD in BRL.
**Parity values**
Type A currencies have parity values quoted in USD (1 CURRENCY in USD).
``` r
olinda_get_currency("CAD", "2017-03-01", "2017-03-01")
#> # A tibble: 3 x 3
#> datetime bid ask
#>
#> 1 2017-03-01 14:37:41 2.32 2.32
#> 2 2017-03-01 15:37:01 2.32 2.32
#> 3 2017-03-01 15:37:01 2.32 2.32
```
``` r
olinda_get_currency("CAD", "2017-03-01", "2017-03-01", parity = TRUE)
#> # A tibble: 3 x 3
#> datetime bid ask
#>
#> 1 2017-03-01 14:37:41 1.33 1.33
#> 2 2017-03-01 15:37:01 1.33 1.33
#> 3 2017-03-01 15:37:01 1.33 1.33
```
Type B currencies have parity values as 1 USD in CURRENCY, see AUD, for
example.
``` r
olinda_get_currency("AUD", "2017-03-01", "2017-03-01")
#> # A tibble: 3 x 3
#> datetime bid ask
#>
#> 1 2017-03-01 14:37:41 2.38 2.38
#> 2 2017-03-01 15:37:01 2.38 2.38
#> 3 2017-03-01 15:37:01 2.38 2.38
```
``` r
olinda_get_currency("AUD", "2017-03-01", "2017-03-01", parity = TRUE)
#> # A tibble: 3 x 3
#> datetime bid ask
#>
#> 1 2017-03-01 14:37:41 0.768 0.768
#> 2 2017-03-01 15:37:01 0.767 0.768
#> 3 2017-03-01 15:37:01 0.767 0.768
```
#### Currency rates
Use currency functions to download
currency rates from the BCB web site.
``` r
rbcb::get_currency("USD", "2017-03-01", "2017-03-10")
#> # A tibble: 8 x 3
#> date bid ask
#>
#> 1 2017-03-01 3.10 3.10
#> 2 2017-03-02 3.11 3.11
#> 3 2017-03-03 3.14 3.14
#> 4 2017-03-06 3.11 3.11
#> 5 2017-03-07 3.12 3.12
#> 6 2017-03-08 3.15 3.15
#> 7 2017-03-09 3.17 3.17
#> 8 2017-03-10 3.16 3.16
```
The rates come quoted in BRL, so 3.0970 is worth 1 USD in BRL.
All currency time series have an attribute called `symbol` that stores
its own currency name.
``` r
attr(rbcb::get_currency("USD", "2017-03-01", "2017-03-10"), "symbol")
#> [1] "USD"
```
Trying another currency.
``` r
get_currency("JPY", "2017-03-01", "2017-03-10") |> Ask()
#> # A tibble: 8 x 2
#> date JPY
#>
#> 1 2017-03-01 0.0273
#> 2 2017-03-02 0.0272
#> 3 2017-03-03 0.0274
#> 4 2017-03-06 0.0274
#> 5 2017-03-07 0.0274
#> 6 2017-03-08 0.0274
#> 7 2017-03-09 0.0276
#> 8 2017-03-10 0.0275
```
To see the avaliable currencies call `list_currencies`.
``` r
rbcb::list_currencies()
#> # A tibble: 218 x 5
#> name code symbol country_name country_code
#>
#> 1 AFEGANE AFEGANIST 5 AFN AFEGANISTAO 132
#> 2 RANDE/AFRICA SUL 785 ZAR AFRICA DO SUL 7560
#> 3 LEK ALBANIA REP 490 ALL ALBANIA, REPUBLICA DA 175
#> 4 EURO 978 EUR ALEMANHA 230
#> 5 KWANZA/ANGOLA 635 AOA ANGOLA 400
#> 6 DOLAR CARIBE ORIENTAL 215 XCD ANGUILLA 418
#> 7 DOLAR CARIBE ORIENTAL 215 XCD ANTIGUA E BARBUDA 434
#> 8 RIAL/ARAB SAUDITA 820 SAR ARABIA SAUDITA 531
#> 9 DINAR ARGELINO 95 DZD ARGELIA 590
#> 10 PESO ARGENTINO 706 ARS ARGENTINA 639
#> # ... with 208 more rows
```
There are 216 currencies available.
#### Cross currency rates
The API provides a matrix with the
relations between exchange rates, this is the matrix of cross currency
rates. This is a square matrix with the all exchange rates between all
currencies.
``` r
x <- rbcb::get_currency_cross_rates("2017-03-10")
dim(x)
#> [1] 156 156
```
``` r
# Since there are many currencies it is interesting to subset the matrix.
cr <- c("USD", "BRL", "EUR", "CAD")
x[cr, cr]
#> USD BRL EUR CAD
#> USD 1.0000000 3.1623 0.9380896 1.3465764
#> BRL 0.3162255 1.0000 0.2966479 0.4258218
#> EUR 1.0659963 3.3710 1.0000000 1.4354454
#> CAD 0.7426240 2.3484 0.6966479 1.0000000
```
The rates are quoted by its columns labels, so the numbers in the BRL
column are worth one currency unit in BRL.