cbrapi

README

Central Bank of Russia API implementation

Package cbrapi partially implements API of Central Bank of Russia. Implemented functions allow to quote currency rates at specified date or range of dates. See website of Central Bank of Russia for details.

Usage is quite simple (see below sample code). The only two points that need to be mentioned are as follows.

1. Methods which accept dates have signatures with interface{} type. These require either time.Time object or date in form of string formatted strictly as "DD/MM/YYYY". Supplying string formatted in a different way would result in a error.

2. ExchangeRate object implements Stringer, so if you care to only receive the float (the rate itself), use relevant field and do not Print/Sprint etc.

See package documentation at pkg.go.dev for details.

To use the library: go get github.com/dmfed/cbrapi

And here comes a working example:

import "https://github.com/dmfed/cbrapi/"

package main

import (
	"fmt"
	"time"

	"github.com/dmfed/cbrapi"
)

func main() {
	usd, err := cbrapi.New("USD")
	if err != nil {
		fmt.Println(err)
		return
	}
	usdrate, err := usd.RateAtDate(time.Now()) // returns current exchange rate USD/RUB
	fmt.Println(usdrate, err)
	eurrate, _ := cbrapi.QuoteAtDate("EUR", "01/09/2020") // returns exchange rate of EUR at September 1st 2020
	fmt.Println(eurrate)
	usdrange, _ := usd.RateAtRangeDates("01/09/2020", "04/09/2020")
	for _, item := range usdrange {
		fmt.Println(item)
	}
}

Documentation

Overview

Package cbrapi implements basic functionality of API of Central Bank of Russia (cbr.ru). It allows to quote exchange rates of currencies in very simple steps

Index

• Variables
• type Currency
  • func New(ISOcode string) (*Currency, error)
  • func (c *Currency) RateAtDate(date interface{}) (ExchangeRate, error)
  • func (c *Currency) RateAtRangeDates(startdate, enddate interface{}) ([]ExchangeRate, error)
• type ExchangeRate
  • func QuoteAtDate(ISOCode string, date interface{}) (ExchangeRate, error)
  • func QuoteAtRangeDates(ISOCode string, startdate, enddate interface{}) ([]ExchangeRate, error)
  • func (r ExchangeRate) String() string
• type ForeignCurrencyAPICodes
• type ForeignCurrencyAPICodesItem
• type ResponseDaily
• type ResponseDailyElement
• type ResponseRange
• type ResponseRangeElement

Variables

var (
	// ErrIncorrectCode is returned if currency code is not supported by the API
	ErrIncorrectCode = errors.New("Provided currency code is not known to the API")
	// ErrNoData is returned if rate for requested date(s) was not found
	ErrNoData = errors.New("API did not provide requested data")
)

var (
	BaseURL               string = "https://www.cbr.ru/scripts/"
	EndpointSingleDate           = BaseURL + "XML_daily.asp?date_req=%v"
	EndpointDateRange            = BaseURL + "XML_dynamic.asp?date_req1=%v&date_req2=%v&VAL_NM_RQ=%v"
	EndpointCurrencyCodes        = BaseURL + "XML_valFull.asp"
)

Types

type Currency

type Currency struct {
	NameRUS     string
	NameENG     string
	APIID       string
	Nominal     int
	ISONumCode  int
	ISOCharCode string
}

Currency represents a currency known to Central Bank of Russia API Fields of this struct are almost identical to what API returns

func New

func New(ISOcode string) (*Currency, error)

New returns instance of Currency object which can be used to request exchange rate of currency from the Central Bank API with RateAtDate() and RateAtRangeDates() methods or QuoteAtDate() and QuoteAtRangeDates() In case of error New returns nil. Make sure to always check error.

func (*Currency) RateAtDate

func (c *Currency) RateAtDate(date interface{}) (ExchangeRate, error)

RateAtDate accept either "DD/MM/YYYY" formatted date or time.Time object. It sends request to the API and returns ExchangeRate object

func (*Currency) RateAtRangeDates

func (c *Currency) RateAtRangeDates(startdate, enddate interface{}) ([]ExchangeRate, error)

RateAtRangeDates accept either "DD/MM/YYYY" formatted date or time.Time object. It sends request to the API and returns slice of ExchangeRate objects

type ExchangeRate

type ExchangeRate struct {
	ISOCode string
	Nominal int
	Date    time.Time
	Rate    float64
}

ExchangeRate represents exchange rate of a currency at specified date.

func QuoteAtDate

func QuoteAtDate(ISOCode string, date interface{}) (ExchangeRate, error)

QuoteAtDate accepts ISO code of currency and either "DD/MM/YYYY" formatted date or time.Time object and returns ExchangeRate object

func QuoteAtRangeDates

func QuoteAtRangeDates(ISOCode string, startdate, enddate interface{}) ([]ExchangeRate, error)

QuoteAtRangeDates accepts ISO code of currency and either "DD/MM/YYYY" formatted dates or time.Time objects where startdate and enddate are both inclusive and returns slice of ExchangeRate objects for corresponding dates

func (ExchangeRate) String

func (r ExchangeRate) String() string

type ForeignCurrencyAPICodes

type ForeignCurrencyAPICodes struct {
	XMLName  xml.Name                      `xml:"Valuta"`
	Elements []ForeignCurrencyAPICodesItem `xml:"Item"`
}

ForeignCurrencyAPICodes is a list of elements representing currencies known to the API of Central Bank.

type ForeignCurrencyAPICodesItem

type ForeignCurrencyAPICodesItem struct {
	XMLName     xml.Name `xml:"Item"`
	APIID       string   `xml:"ID,attr"`
	Name        string   `xml:"Name"`
	EngName     string   `xml:"EngName"`
	Nominal     int      `xml:"Nominal"`
	ISONumCode  int      `xml:"ISO_Num_Code"`
	ISOCharCode string   `xml:"ISO_Char_Code"`
}

ForeignCurrencyAPICodesItem represents XML structure of currency item returned by the API

type ResponseDaily

type ResponseDaily struct {
	XMLName  xml.Name               `xml:"ValCurs"`
	Date     string                 `xml:"Date,attr"`
	Elements []ResponseDailyElement `xml:"Valute"`
}

ResponseDaily represents XML structure of response to request of singe date exchange rates from the endpoint This response contains all currencies rates as of the requested date

type ResponseDailyElement

type ResponseDailyElement struct {
	XMLName       xml.Name `xml:"Valute"`
	APIID         string   `xml:"ID,attr"`
	NumericCode   int      `xml:"NumCode"`
	CharacterCode string   `xml:"CharCode"`
	Nominal       int      `xml:"Nominal"`
	Name          string   `xml:"Name"`
	Value         string   `xml:"Value"`
}

ResponseDailyElement represents XML element of ResponseDaily

type ResponseRange

type ResponseRange struct {
	XMLName   xml.Name               `xml:"ValCurs"`
	APIID     string                 `xml:"ID,attr"`
	DateStart string                 `xml:"DateRange1,attr"`
	DateEnd   string                 `xml:"DateRange2,attr"`
	Elements  []ResponseRangeElement `xml:"Record"`
}

ResponseRange list of exchange rates for requested dates

type ResponseRangeElement

type ResponseRangeElement struct {
	XMLName xml.Name `xml:"Record"`
	Date    string   `xml:"Date,attr"`
	APIID   string   `xml:"Id,attr"`
	Nominal int      `xml:"Nominal"`
	Value   string   `xml:"Value"`
}

ResponseRangeElement represents exchange rate for single date