Go library for NBP (National Bank of Poland) API: http://api.nbp.pl/en.html
The library is used in the kursNBP project: https://github.com/pjaskulski/kursnbp
To install and use:
go get https://github.com/pjaskulski/nbpapi
To clone the repo and invoke the tests:
git clone https://github.com/pjaskulski/nbpapi
cd nbpapi
make test
make coverWarning: by default some tests use (great) httpmock library, to use the real NBP API service it is necessary to set the USEMOCK environment variable to '0'
// How to get table A of currency exchange rates published
// on 12 Nov 2020: function TableByDate("2020-11-12") fetch data, then
// one can get data from nbpTable.Exchange structures (or
// nbpTable.ExchangeC structures, depending of the type of
// table of exchange rates)
var tableNo string
client := nbpapi.NewTable("A")
err: = client.TableByDate("2020-11-12")
if err != nil {
log.Fatal(err)
}
for _, item := range client.Exchange {
tableNo = item.No
for _, currencyItem := range item.Rates {
fmt.Println(tableNo, currencyItem.Code, currencyItem.Currency, currencyItem.Mid)
}
}Output:
221/A/NBP/2020 THB bat (Tajlandia) 0.1256
221/A/NBP/2020 USD dolar amerykański 3.7995
221/A/NBP/2020 AUD dolar australijski 2.7636
221/A/NBP/2020 HKD dolar Hongkongu 0.4901
221/A/NBP/2020 CAD dolar kanadyjski 2.9074
221/A/NBP/2020 NZD dolar nowozelandzki 2.6119
221/A/NBP/2020 SGD dolar singapurski 2.8171
221/A/NBP/2020 EUR euro 4.4868
221/A/NBP/2020 HUF forint (Węgry) 0.012648
221/A/NBP/2020 CHF frank szwajcarski 4.1573
[...]
// today's gold price: function GetPriceToday returns GoldPrice struct
gold := nbpapi.NewGold()
price, err := gold.GetPriceToday()
if err != nil {
fmt.Println(err)
} else {
fmt.Println("Publication date: ", price.Data)
fmt.Println("Price of 1g of gold (PLN): ", price.Price)
}Output:
Publication date: 2020-11-27
Price of 1g of gold (PLN): 218.41
More examples in the \ example folder.
- NBPTable type - complete tables of currency exchange rates:
- create new:
client := NewTable("C") - methods that downloading data into NBPTable type structures:
- TableRaw (only raw data: json or xml)
- TableByDate (raw data and and structures filled with data)
- TableLast (as above)
- methods that return structures with tables of currency exchange rates:
- GetTableCurrent
- GetTableCCurrent
- GetTableToday
- GetTableCToday
- GetTableByDay
- GetTableCByDay
- methods that return data (downloaded previously by TableByDate, or TableLast methods) as text, ready to be printed or saved to a file:
- CreatePrettyOutput
- CreateCSVOutput
- CreateRawOutput
- other methods:
- SetTableType
- create new:
- NBPCurrency type - particular currency exchange rates:
- create new:
client := NewCurrency("A") - methods that downloading data into NBPCurrency type structures:
- CurrencyRaw (only raw data: json or xml)
- CurrencyByDate (raw data and and structures filled with data)
- CurrencyLast (as above)
- CurrencyToday (as above)
- methods that return structures with currency rates:
- GetRateCurrent
- GetRateToday
- GetRateByDate
- methods that return data (downloaded previously) as text, ready to be printed or saved to a file:
- CreatePrettyOutput
- CreateCSVOutput
- CreateRawOutput
- other methods:
- SetTableType
- create new:
- NBPGold type - gold prices:
- create new:
client := NewGold() - methods that downloading data into NBPGold type structures:
- GoldRaw (only raw data: json or xml)
- GoldByDate (raw data and and structures filled with data)
- GoldLast (as above)
- methods that return structures with prices of gold:
- GetPriceToday
- GetPriceCurrent
- GetPriceByDate
- methods that return data (downloaded previously) as text, ready to be printed or saved to a file:
- CreatePrettyOutput
- CreateCSVOutput
- CreateRawOutput
- create new:
Detailed documentation:
package nbpapi // import "github.com/pjaskulski/nbpapi"
VARIABLES
var (
ErrInvalidCurrencyCode error = errors.New("Invalid currency code")
ErrInvalidTableType error = errors.New("Invalid table type, allowed values: A, B or C")
)
errors for invalid code, table type
var CurrencyValuesA = []string{"THB", "USD", "AUD", "HKD", "CAD", "NZD", "SGD", "EUR", "HUF", "CHF",
"GBP", "UAH", "JPY", "CZK", "DKK", "ISK", "NOK", "SEK", "HRK", "RON",
"BGN", "TRY", "ILS", "CLP", "PHP", "MXN", "ZAR", "BRL", "MYR", "RUB",
"IDR", "INR", "KRW", "CNY", "XDR"}
CurrencyValuesA - list of supported currencies for table type A
var CurrencyValuesB = []string{"MGA", "PAB", "ETB", "AFN", "VES", "BOB", "CRC", "SVC", "NIO", "GMD",
"MKD", "DZD", "BHD", "IQD", "JOD", "KWD", "LYD", "RSD", "TND", "MAD",
"AED", "STN", "BSD", "BBD", "BZD", "BND", "FJD", "GYD", "JMD", "LRD",
"NAD", "SRD", "TTD", "XCD", "SBD", "ZWL", "VND", "AMD", "CVE", "AWG",
"BIF", "XOF", "XAF", "XPF", "DJF", "GNF", "KMF", "CDF", "RWF", "EGP",
"GIP", "LBP", "SSP", "SDG", "SYP", "GHS", "HTG", "PYG", "ANG", "PGK",
"LAK", "MWK", "ZMW", "AOA", "MMK", "GEL", "MDL", "ALL", "HNL", "SLL",
"SZL", "LSL", "AZN", "MZN", "NGN", "ERN", "TWD", "TMT", "MRU", "TOP",
"MOP", "ARS", "DOP", "COP", "CUP", "UYU", "BWP", "GTQ", "IRR", "YER",
"QAR", "OMR", "SAR", "KHR", "BYN", "LKR", "MVR", "MUR", "NPR", "PKR",
"SCR", "PEN", "KGS", "TJS", "UZS", "KES", "SOS", "TZS", "UGX", "BDT",
"WST", "KZT", "MNT", "VUV", "BAM"}
CurrencyValuesB - list of supported currencies for table type B
var CurrencyValuesC = []string{"USD", "AUD", "CAD", "EUR", "HUF", "CHF", "GBP", "JPY", "CZK", "DKK", "NOK",
"SEK", "XDR"}
CurrencyValuesC - list of supported currencies for table type C
var TableValues = []string{"A", "B", "C"}
TableValues - list of table types
FUNCTIONS
func IsValidXML(input string) bool
IsValidXML - func from:
https://stackoverflow.com/questions/53476012/how-to-validate-a-xml
TYPES
type ExchangeTable struct {
Table string `json:"table"`
No string `json:"no"`
EffectiveDate string `json:"effectiveDate"`
Rates []rateTable `json:"rates"`
}
ExchangeTable type
type ExchangeTableC struct {
Table string `json:"table"`
No string `json:"no"`
TradingDate string `json:"tradingDate"`
EffectiveDate string `json:"effectiveDate"`
Rates []rateTableC `json:"rates"`
}
ExchangeTableC type
type GoldRate struct {
Data string `json:"data"`
Price float64 `json:"cena"`
}
GoldRate type
type NBPCurrency struct {
Exchange exchangeCurrency
ExchangeC exchangeCurrencyC
Client *http.Client
// Has unexported fields.
}
NBPCurrency type
func NewCurrency(tableType string) *NBPCurrency
NewCurrency - function creates new currency type
func (c *NBPCurrency) CreateCSVOutput(lang string) string
CreateCSVOutput - function returns currency rates, in the form of CSV (data
separated by a comma), depending on the tableType field: for type A and B
tables a column with an average rate is printed, for type C two columns: buy
price and sell price
Parameters:
lang - 'en' or 'pl'
func (c *NBPCurrency) CreatePrettyOutput(lang string) string
CreatePrettyOutput - function returns exchange rates as formatted table
depending on the tableType field: for type A and B tables a column with an
average rate is printed, for type C two columns: buy price and sell price
Parameters:
lang - 'en' or 'pl'
func (c *NBPCurrency) CreateRawOutput() string
CreateRawOutput - function print just result of request (json or xml)
func (c *NBPCurrency) CurrencyByDate(code, date string) error
CurrencyByDate - function downloads and writes data to exchange (exchangeC)
slice, raw data (json) still available in result field
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
func (c *NBPCurrency) CurrencyLast(code string, last int) error
CurrencyLast - function downloads and writes data to exchange (exchangeC)
slice, raw data (json) still available in result field
Function returns error or nil
Parameters:
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
last - as an alternative to date, the last <n> tables/rates
can be retrieved
func (c *NBPCurrency) CurrencyRaw(code, date string, last int, format string) error
CurrencyRaw - function downloads data in json or xml form
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
last - as an alternative to date, the last <n> tables/rates
can be retrieved
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
format - 'json' or 'xml'
func (c *NBPCurrency) CurrencyToday(code string) error
CurrencyToday - function downloads and writes data to exchange (exchangeC)
slice, raw data (json) still available in result field
Function returns error or nil
Parameters:
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
func (c *NBPCurrency) GetRateByDate(code, date string) ([]Rate, error)
GetRateByDate - function downloads today's currency exchange rate and
returns slice of Rate struct (or error)
Parameters:
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
func (c *NBPCurrency) GetRateCurrent(code string) (Rate, error)
GetRateCurrent - function downloads current currency exchange rate and
return Rate struct (or error)
Parameters:
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
func (c *NBPCurrency) GetRateToday(code string) (Rate, error)
GetRateToday - function downloads today's currency exchange rate and returns
Rate struct (or error)
Parameters:
code - ISO 4217 currency code, depending on the type of the
table available currencies may vary
func (c *NBPCurrency) SetTableType(tableType string) error
SetTableType - the function allows to set the supported type of exchange
rate table
type NBPGold struct {
GoldRates []GoldRate
Client *http.Client
// Has unexported fields.
}
NBPGold type
func NewGold() *NBPGold
NewGold - function creates new gold type
func (g *NBPGold) CreateCSVOutput(lang string) string
CreateCSVOutput - function returns prices of gold in CSV format (comma
separated data)
Parameters:
lang - 'en' or 'pl'
func (g *NBPGold) CreatePrettyOutput(lang string) string
CreatePrettyOutput - function returns a formatted table of gold prices
Parameters:
lang - 'en' or 'pl'
func (g *NBPGold) CreateRawOutput() string
CreateRawOutput - function returns just result of request (json or xml)
func (g *NBPGold) GetPriceByDate(date string) ([]GoldRate, error)
GetPriceByDate - function returns gold prices (as slice of struct), by date
("YYYY-MM-DD") or range of dates ("YYYY-MM-DD:YYYY-MM-DD")
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(price for today) or 'current' - current gold price (last published)
func (g *NBPGold) GetPriceCurrent() (GoldRate, error)
GetPriceCurrent - function downloads and returns current gold price as
GoldRate struct
func (g *NBPGold) GetPriceToday() (GoldRate, error)
GetPriceToday - function downloads and returns today's gold price, as
GoldRate struct
func (g *NBPGold) GoldByDate(date string) error
GoldByDate - function downloads and writes data to goldRates slice, raw data
(json) still available in NBPGold.result field
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(price for today) or 'current' - current gold price (last published)
func (g *NBPGold) GoldLast(last int) error
GoldLast - function downloads and writes data to GoldRates slice, raw data
(json) still available in NBPGold.result field
Function returns error or nil
Parameters:
last - as an alternative to date, the last <n> prices of gold
can be retrieved
func (g *NBPGold) GoldRaw(date string, last int, format string) error
GoldRaw - function downloads data in json or xml form
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(price for today) or 'current' - current gold price (last published)
last - as an alternative to date, the last <n> prices of gold
can be retrieved
format - 'json' or 'xml'
type NBPTable struct {
Exchange []ExchangeTable
ExchangeC []ExchangeTableC
Client *http.Client
// Has unexported fields.
}
NBPTable type
func NewTable(tableType string) *NBPTable
NewTable - function creates new table type
func (t *NBPTable) CreateCSVOutput(lang string) string
CreateCSVOutput - function prints tables of exchange rates in the console,
in the form of CSV (data separated by a comma), depending on the tableType
field: for type A and B tables a column with an average rate is printed, for
type C two columns: buy price and sell price
Parameters:
lang - 'en' or 'pl'
func (t *NBPTable) CreatePrettyOutput(lang string) string
CreatePrettyOutput - function returns tables of exchange rates as formatted
table, depending on the tableType field: for type A and B tables a column
with an average rate is printed, for type C two columns: buy price and sell
price
Parameters:
lang - 'en' or 'pl'
func (t *NBPTable) CreateRawOutput() string
CreateRawOutput - function returns just result of request (json or xml)
func (t *NBPTable) GetTableByDate(date string) ([]ExchangeTable, error)
GetTableByDate - function retrieves a table of exchange rates for a given
day and return slice of struct ExchangeTable (or error). Version for table
A, B (mid - average price)
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
func (t *NBPTable) GetTableCByDate(date string) ([]ExchangeTableC, error)
GetTableCByDate - function retrieves a table of exchange rates for a given
day and return slice of struct ExchangeTable (or error). Version for table C
(ask, bid - buy, sell prices)
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
func (t *NBPTable) GetTableCCurrent() ([]ExchangeTableC, error)
GetTableCCurrent - function downloads current table of currency exchange
rates and return slice of struct ExchangeTableC (or error), version for
table C (bid, ask - buy, sell prices)
func (t *NBPTable) GetTableCToday() ([]ExchangeTableC, error)
GetTableCToday - function downloads today's table of currency exchange rates
and return slice of struct ExchangeTableC (or error), version for table C
(bid, ask - buy, sell prices)
func (t *NBPTable) GetTableCurrent() ([]ExchangeTable, error)
GetTableCurrent - function downloads current table of currency exchange
rates and return slice of struct ExchangeTable (or error), version for table
A, B (mid - average price)
func (t *NBPTable) GetTableToday() ([]ExchangeTable, error)
GetTableToday - function downloads today's table of currency exchange rates
and return slice of struct ExchangeTable (or error), version for table A, B
(mid - average price)
func (t *NBPTable) SetTableType(tableType string) error
SetTableType - the function allows to set the supported type of exchange
rate table
func (t *NBPTable) TableByDate(date string) error
TableByDate - function downloads and writes data to NBPTable.Exchange
(NBPTable.ExchangeC) slice, raw data (json) still available in
NBPTable.result field
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
func (t *NBPTable) TableLast(last int) error
TableLast - function downloads and writes data to NBPTable.Exchange
(NBPTable.ExchangeC) slice, raw data (json) still available in
NBPTable.result field
Function returns error or nil
Parameters:
last - the last <n> tables/rates can be retrieved
func (t *NBPTable) TableRaw(date string, last int, format string) error
TableRaw - function downloads data in json or xml form, the data will be
placed as [] byte in the result field
Function returns error or nil
Parameters:
date - date in the format: 'YYYY-MM-DD' (ISO 8601 standard),
or a range of dates in the format: 'YYYY-MM-DD:YYYY-MM-DD' or 'today'
(rate for today) or 'current' - current table / rate (last published)
last - as an alternative to date, the last <n> tables/rates
can be retrieved
format - 'json' or 'xml'
type Rate struct {
No string
EffectiveDate string
Mid float64
Bid float64
Ask float64
}
Rate type
- more tests