currconv

package module
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2023 License: MIT Imports: 7 Imported by: 0

README

Currency Converter API

A GoLang wrapper of Currency Converter API.

You can use Currency Converter API to easily query conversion between difference currencies and check historical rate with a given date range.

Installation

Use go get

go get github.com/kitloong/go-currency-converter-api/v2

Then import

import "github.com/kitloong/go-currency-converter-api/api"

Usage

Firstly, create an API instance with

Name Description
BaseURL The API server URL, refer to https://www.currencyconverterapi.com/docs for details
Version The API version number, latest is v7.
APIKey Your secret API key. 
api := currconv.NewAPI(currconv.Config{
    BaseURL: "https://free.currconv.com",
    Version: "v7",
    APIKey:  "[KEY]",
})

Available methods:

Convert

Returns the currency conversion rate with [FROM]_[TO] request.

To convert currency from USD to MYR, construct a request struct and set USD_MYR to the Q field:

convert, err := api.Convert(currconv.ConvertRequest{
    Q: []string{"USD_MYR"},
})

// convert
// &{
//     Query: {
//         Count: 1
//     }
//     Results: map[
//         "USD_MYR": {
//             ID:  "USD_MYR"
//             Val: 4.348493
//             To:  "MYR"
//             Fr:  "USD"
//         }
//     ]
// }

Since Q is a string slice, you can append more currencies to request multiple conversion in a single request:

convert, err := api.Convert(currconv.ConvertRequest{
    Q: []string{"USD_MYR", "MYR_USD"},
})

// convert
// &{
//     Query: {
//         Count: 2
//     }
//     Results: map[
//         "MYR_USD": {
//             ID:  "MYR_USD"
//             Val: 0.229964
//             To:  "USD"
//             Fr:  "MYR"
//         }
//         "USD_MYR": {
//             ID:  "USD_MYR"
//             Val: 4.348493
//             To:  "MYR"
//             Fr:  "USD"
//         }
//     ]
// }
ConvertCompact

Returns conversion result with compact mode:

convert, err := api.ConvertCompact(currconv.ConvertRequest{
    Q: []string{"USD_MYR", "MYR_USD"},
})

// convert
// map[
//     "MYR_USD": 0.229964
//     "USD_MYR": 4.348493
// ]
ConvertHistorical

Returns historical currency conversion rate data:

convert, err := api.ConvertHistorical(currconv.ConvertHistoricalRequest{
    Q:    []string{"USD_MYR", "MYR_USD"},
    Date: time.Date(2023, 2, 14, 0, 0, 0, 0, time.UTC),
})

// convert
// &{
//     Query: {
//         Count: 2
//     }
//     Date: "2023-02-14"
//     Results: map[
//         "MYR_USD": {
//             ID:  "MYR_USD"
//             To:  "USD"
//             Fr:  "MYR"
//             Val: map[
//                 "2023-02-14": 0.229965
//             ]}
//         "USD_MYR": {
//             ID:  "USD_MYR"
//             To:  "MYR"
//             Fr:  "USD"
//             Val: map[
//                 "2023-02-14": 4.348497
//             ]
//         }
//     ]
// }

Set EndDate to request historical data with date range:

convert, err := api.ConvertHistorical(currconv.ConvertHistoricalRequest{
    Q:       []string{"USD_MYR", "MYR_USD"},
    Date:    time.Date(2023, 2, 1, 0, 0, 0, 0, time.UTC),
    EndDate: time.Date(2023, 2, 5, 0, 0, 0, 0, time.UTC),
})

// convert
// &{
//     Query:{
//         Count: 2
//     }
//     Date: "2023-02-01"
//     EndDate: "2023-02-05"
//     Results: map[
//         "MYR_USD": {
//             ID:  "MYR_USD"
//             To:  "USD"
//             Fr:  "MYR"
//             Val: map[
//                 "2023-02-01": 0.234411
//                 "2023-02-02": 0.235513
//                 "2023-02-03": 0.23485
//                 "2023-02-04": 0.23485
//                 "2023-02-05": 0.234851
//             ]}
//         "USD_MYR": {
//             ID:  "USD_MYR"
//             To:  "MYR"
//             Fr:  "USD"
//             Val: map[
//                 "2023-02-01": 4.266011
//                 "2023-02-02": 4.246055
//                 "2023-02-03": 4.258039
//                 "2023-02-04": 4.258039
//                 "2023-02-05": 4.258023
//             ]
//         }
//     ]
// }
ConvertHistoricalCompact

Returns historical data with compact mode:

convert, err := api.ConvertHistoricalCompact(currconv.ConvertHistoricalRequest{
    Q:       []string{"USD_MYR", "MYR_USD"},
    Date:    time.Date(2023, 2, 1, 0, 0, 0, 0, time.UTC),
    EndDate: time.Date(2023, 2, 5, 0, 0, 0, 0, time.UTC),
})

// convert
// map[
//     "2023-02-01": 4.266011
//     "2023-02-02": 4.246055
//     "2023-02-03": 4.258039
//     "2023-02-04": 4.258039
//     "2023-02-05": 4.258023
// ]
Currencies

Returns a list of currencies:

currencies, err := api.Currencies()

// currencies
// &{
//     Results:map[
//         "MYR": {
//             ID:             "MYR"
//             CurrencyName:   "Malaysian Ringgit"
//             CurrencySymbol: "RM"
//         }
//         "USD": {
//             ID:             "USD"
//             CurrencyName:   "United States Dollar"
//             CurrencySymbol: "$"
//         }
//         ...
//     ]
// }
Countries

Returns a list of countries:

countries, err := api.Countries()

// countries
// &{
//     Results: map[
//         "MY": {
//             ID:             "MY"
//             Alpha3:         "MYS"
//             CurrencyID:     "MYR"
//             CurrencyName:   "Malaysian ringgit"
//             CurrencySymbol: "RM"
//             Name:           "Malaysia"
//         }
//         "US": {
//             ID:             "US"
//             Alpha3:         "USA"
//             CurrencyID:     "USD"
//             CurrencyName:   "United States dollar"
//             CurrencySymbol: "$"
//             Name:           "United States of America"
//         }
//         ...
//     ]
// }
Usage

Returns your current API usage:

usage, err := api.Usage()

// usage
// &{
//     Timestamp: "2023-02-15 02:05:49.988 +0000 UTC"
//     Usage: 1
// }

License

The project is open-sourced software licensed under the MIT license

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type API 

type API struct {
	// contains filtered or unexported fields
}

API is the wrapper implementation of CurrencyConverterAPI.

func NewAPI 

func NewAPI(config Config) *API

NewAPI create and return an API.

func (*API) Convert 

func (a *API) Convert(req ConvertRequest) (result *Convert, err error)

Convert returns the currency conversion rate with `[FROM]_[TO]` request.

func (*API) ConvertCompact 

func (a *API) ConvertCompact(req ConvertRequest) (result ConvertCompact, err error)

ConvertCompact returns conversion result with compact mode.

func (*API) ConvertHistorical 

func (a *API) ConvertHistorical(req ConvertHistoricalRequest) (result *ConvertHistorical, err error)

ConvertHistorical returns historical currency conversion rate data with target date or date range.

func (*API) ConvertHistoricalCompact 

func (a *API) ConvertHistoricalCompact(req ConvertHistoricalRequest) (result ConvertHistoricalCompact, err error)

ConvertHistoricalCompact returns historical data with compact mode.

func (*API) Countries 

func (a *API) Countries() (result *Country, err error)

Countries returns a list of countries.

func (*API) Currencies 

func (a *API) Currencies() (result *Currency, err error)

Currencies returns a list of currencies.

func (*API) Usage 

func (a *API) Usage() (result *Usage, err error)

Usage returns your current API usage.

type Config 

type Config struct {
	BaseURL string
	Version string
	APIKey  string
}

Config of the API.

type Convert 

type Convert struct {
	Query struct {
		Count int `json:"count"`
	} `json:"query"`
	Results map[string]struct {
		ID  string  `json:"id"`
		Val float32 `json:"val"`
		To  string  `json:"to"`
		Fr  string  `json:"fr"`
	} `json:"results"`
}

Convert is the result of the Convert API.

type ConvertCompact 

type ConvertCompact map[string]float32

ConvertCompact is the compact result of the ConvertCompact API.

type ConvertHistorical 

type ConvertHistorical struct {
	Query struct {
		Count int `json:"count"`
	} `json:"query"`
	Date    string `json:"date"`
	EndDate string `json:"endDate,omitempty"`
	Results map[string]struct {
		ID  string             `json:"id"`
		To  string             `json:"to"`
		Fr  string             `json:"fr"`
		Val map[string]float32 `json:"val"`
	} `json:"results"`
}

ConvertHistorical is the result of ConvertHistorical API.

type ConvertHistoricalCompact 

type ConvertHistoricalCompact map[string]map[string]float32

ConvertHistoricalCompact is the compact result of ConvertHistoricalCompact API.

type ConvertHistoricalRequest 

type ConvertHistoricalRequest struct {
	// Q is the same with ConvertRequest's Q.
	Q []string
	// Date is the target historical date that you want to request from.
	Date time.Time
	// EndDate form a date range with Date, returns historical data in within the date range.
	EndDate time.Time
}

ConvertHistoricalRequest contains request fields of ConvertHistorical and ConvertHistoricalCompact API.

type ConvertRequest 

type ConvertRequest struct {
	// Q is the currency conversion parameter in "[FROM]_[TO]" format.
	// To get MYR -> USD conversion rate, uses "MYR_USD".
	// A multiple Q request will return multiple conversion in a single request.
	Q []string
}

ConvertRequest contains request fields of Convert and ConvertCompact API.

type Country 

type Country struct {
	Results map[string]struct {
		ID             string `json:"id"`
		Alpha3         string `json:"alpha3"`
		CurrencyID     string `json:"currencyId"`
		CurrencyName   string `json:"currencyName"`
		CurrencySymbol string `json:"currencySymbol"`
		Name           string `json:"name"`
	} `json:"results"`
}

Country is the result of Country API.

type Currency 

type Currency struct {
	Results map[string]struct {
		ID             string `json:"id"`
		CurrencyName   string `json:"currencyName"`
		CurrencySymbol string `json:"currencySymbol"`
	} `json:"results"`
}

Currency is the result of Currencies API.

type Error 

type Error struct {
	Status int    `json:"status"`
	Error  string `json:"error"`
}

type Usage 

type Usage struct {
	Timestamp time.Time `json:"timestamp"`
	Usage     int       `json:"usage"`
}

Usage is the result of Usage API.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.