API Documentation
BrazilCentralBank — ModuleThe BrazilCentralBank package aims to provide a user interface to Brazil's Central Bank (BCB) web data API.
AUTHOR: azeredo-e@github
GITHUB: github.com/azeredo-e/BCB.jl
LICENSE: MIT License
VERSION: 0.1.0
BrazilCentralBank.getcurrency_list — Methodget_currency_list(;convert_to_utf=true) -> DataFrameList all avaliables currencies in the BCB API, as well as basic information such as currency code, country of origin, etc.
Args:
converttoutf (Bool, optional): By default BCB information comes in the ISO-8859-1 encoding, different from the UTF-8 pattern used by Julia. This argument forces the API result to come in UTF-8, preventing encoding errors. Defaults to true.
Returns:
DataFrames.DataFrame: DataFrame with all avaliable currencies information.
Examples:
julia> getcurrency_list()
273×7 DataFrame
Row │ code name symbol country_code country_name ⋯
│ Int32 String String Int32 String ⋯
─────┼──────────────────────────────────────────────────────────────────────────
1 │ 5 AFEGANE AFEGANIST AFN 132 AFEGANISTAO ⋯
2 │ 785 RANDE/AFRICA SUL ZAR 7560 AFRICA DO SU
3 │ 490 LEK ALBANIA REP ALL 175 ALBANIA, REP
4 │ 610 MARCO ALEMAO DEM 230 ALEMANHA
5 │ 978 EURO EUR 230 ALEMANHA ⋯
6 │ 690 PESETA/ANDORA ADP 370 ANDORRA
7 │ 635 KWANZA/ANGOLA AOA 400 ANGOLA
8 │ 215 DOLAR CARIBE ORIENTAL XCD 418 ANGUILLA
⋮ │ ⋮ ⋮ ⋮ ⋮ ⋱
267 │ 26 BOLIVAR VENEZUELANO VEF 8508 VENEZUELA ⋯
268 │ 260 DONGUE/VIETNAN VND 8583 VIETNA
269 │ 220 DOLAR DOS EUA USD 8630 VIRGENS,ILHA
270 │ 220 DOLAR DOS EUA USD 8664 VIRGENS,ILHA
271 │ 766 QUACHA ZAMBIA ZMW 8907 ZAMBIA ⋯
272 │ 765 QUACHA ZAMBIA ZMK 8907 ZAMBIA
273 │ 217 DOLAR ZIMBABUE ZWL 6653 ZIMBABUE
3 columns and 258 rows omittedBrazilCentralBank.Currency — TypeInstance of the Currency type.
A Currency is an instance of the Currency type attribuited to a specific currency supported by the BrazilCentralBank.jl API, you can check the list of avaliable currencies with. getcurrency_list().
A Currency has many fields that describe not only the information for the coin but also provides methods applied directly on the instance for retrieving information about the currency. For more notes on the implementation check the "Strucs Methods" section in the documentation.
Fields
code(<:Integer): Currency code as in getcurrency_list.
name(<:AbstractString): Name of the currency.
symbol(<:AbstractString): ISO three letter currency code.
countrycode(<:AbstractString): ISO country code.
countryname(<:AbstractString): Country name in portuguese.
type(<:AbstractString): In ype A currencies, to convert the value to USD divide the currency. In type B
you multiply.
exclusion_date(<:AbstractTime): Exclusion date of currency. When it was discontinued.
"Methods"
getforex(target::Union{AbstractString, Array{AbstractString}}; kwargs...)Args
target(Union{AbstractString, Array{AbstractString}}): ISO code of selected currencies.
kwargs: kwargs passed to gettimeseries()
Returns
DataFrame: Selected currencies information.
BrazilCentralBank.Currency — MethodCurrency(code::Integer) -> CurrencyA Currency is an instance of the Currency type attribuited to a specific currency supported by the BrazilCentralBank.jl API, you can check the list of avaliable currencies with. getcurrency_list().
A Currency has many fields that describe not only the information for the coin but also provides methods applied directly on the instance for retrieving information about the currency. For more notes on the implementation check the "Strucs Methods" section in the documentation.
Args
code(Integer): Code for the currency as is in getcurrency_list().
Returns
Currency: Desired currency ```
BrazilCentralBank.Currency — MethodCurrency(code::String) -> CurrencyA Currency is an instance of the Currency type attribuited to a specific currency supported by the BrazilCentralBank.jl API, you can check the list of avaliable currencies with. getcurrency_list().
A Currency has many fields that describe not only the information for the coin but also provides methods applied directly on the instance for retrieving information about the currency. For more notes on the implementation check the "Strucs Methods" section in the documentation.
Args:
symbol(String): ISO three letter code for the currency.
Returns
Currency: Desired currency
BrazilCentralBank.getcurrencyseries — Methodgetcurrencyseries(symbols::Union{String, Array},
start::Any,
finish::Any,
side::String="ask",
groupby::String="symbol")DataFrame with the time series of selected currencies.
Args:
symbol (Union{String, Array}): ISO code of desired currencies.
start (Union{AbstractTime, AbstractString, Number}): Desired start date. The type are set this way because it can accept any valid input to Dates.Date().
end (Union{AbstractTime, AbstractString, Number}): Desired end date.
side (String, optional): Which FOREX prices to return "ask" prices, "side" prices or "both". Defaults to "ask".
groupby (String, optional): In what way the columns are grouped, "symbol" or "side".
Returns:
DataFrames.DataFrame: DataFrame with foreign currency prices.
Raises:
ArgumentError: Values passed to side or groupby are not valid.
Examples:
julia> getcurrencyseries("USD", "2023-12-01", "2023-12-10")
6×2 DataFrame
Row │ Date ask_USD
│ Date Float64
─────┼─────────────────────
1 │ 2023-12-01 4.9191
2 │ 2023-12-04 4.9091
3 │ 2023-12-05 4.9522
4 │ 2023-12-06 4.9031
5 │ 2023-12-07 4.8949
6 │ 2023-12-08 4.9158BrazilCentralBank.gettimeseries — Methodgettimeseries(codes; start=nothing, finish=nothing,
last=0, multi=true)Returns a DataFrame with the SGS time series.
Args
codes(Integer, AbstractString, Dict{AbstractString, Number}, Tuple{Integer, Vararg{Int}}):
The codes for the desired time series.
The codes can be in one of the following formats:
- Integer: time-series code
- Tuple: tuple containing the desired time-series' codes
- Dict: Dictionary with the pair ("SeriesName" => code)
When using a Dict, you can define a name for the series. This is the name to be used in the column name, if not defined, it will default to the code.
start(Number, String...): Any value that can be converted to a date with Date() is valid.
Start date of the series.
end(Number, String...): Any value that can be converted to a date with Date() is valid.
End date of the series.
last(Integer): If last is bigger than 0, start and end are ignored. Return the last n values of the series.
multi(Bool): If true, returns a single series with multiple variable, if false, returns a tuple of single variable series.
Returns
DataFrame: univariate or multivariate time series when multi=true. Vector{DataFrame}: vector of univariate time series when multi=false.
Raises
ErrorException: Failed to fetch time-series data.
Examples
julia> gettimeseries(1, last=5)
5×2 DataFrame
Row │ Date 1
│ Date Float64
─────┼─────────────────────
1 │ 2024-04-16 5.2635
2 │ 2024-04-17 5.2469
3 │ 2024-04-18 5.2512
4 │ 2024-04-19 5.2269
5 │ 2024-04-22 5.2043
julia> gettimeseries(Dict("USDBRL" => 1), last=5)
5×2 DataFrame
Row │ Date USDBRL
│ Date Float64
─────┼─────────────────────
1 │ 2024-04-15 5.1746
2 │ 2024-04-16 5.2635
3 │ 2024-04-17 5.2469
4 │ 2024-04-18 5.2512
5 │ 2024-04-19 5.2269
julia> gettimeseries(Dict("USDBRL" => 1), start="2021-01-18", finish="2021-01-22")
5×2 DataFrame
Row │ Date USDBRL
│ Date Float64
─────┼─────────────────────
1 │ 2021-01-18 5.2788
2 │ 2021-01-19 5.2945
3 │ 2021-01-20 5.3033
4 │ 2021-01-21 5.3166
5 │ 2021-01-22 5.4301
julia> gettimeseries((1, 433), last=5)
10×3 DataFrame
Row │ Date 1 433
│ Date Float64? Float64?
─────┼──────────────────────────────────────
1 │ 2023-11-01 missing 0.28
2 │ 2023-12-01 missing 0.56
3 │ 2024-01-01 missing 0.42
4 │ 2024-02-01 missing 0.83
5 │ 2024-03-01 missing 0.16
6 │ 2024-04-16 5.2635 missing
7 │ 2024-04-17 5.2469 missing
8 │ 2024-04-18 5.2512 missing
9 │ 2024-04-19 5.2269 missing
10 │ 2024-04-22 5.2043 missing
julia> gettimeseries((1, 433), last=5, multi=false)
2-element Vector{DataFrames.DataFrame}:
5×2 DataFrame
Row │ Date 1
│ Date Float64
─────┼─────────────────────
1 │ 2024-04-16 5.2635
2 │ 2024-04-17 5.2469
3 │ 2024-04-18 5.2512
4 │ 2024-04-19 5.2269
5 │ 2024-04-22 5.2043
5×2 DataFrame
Row │ Date 433
│ Date Float64
─────┼─────────────────────
1 │ 2023-11-01 0.28
2 │ 2023-12-01 0.56
3 │ 2024-01-01 0.42
4 │ 2024-02-01 0.83
5 │ 2024-03-01 0.16