Seamlessly Add Live Currency Rates to Your GoLang Projects

Instantiating the Golang Client

To start using the package, create a new client instance by providing your API key:

client := currencyapi.Client("YOUR_API_KEY")

Fetching Live Currency Rates Using Go

Our most common endpoint for developers is our Rates endpoint. Here's how you can retrieve live currency rates using our Go SDK

Firstly, lets create a Strut to handle our JSON response:

type JsonResponse struct {
    Valid bool `json:"valid"`
    Result map[string]interface{} `json:"rates"`
    Error *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

Then lets setup some parameters and get some live currency api data using Go.

package main

import (
    "fmt"
    "encoding/json"
    "github.com/houseofapis/currencyapi-go"
)

type JsonResponse struct {
    Valid bool `json:"valid"`
    Result map[string]interface{} `json:"rates"`
    Error *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

func main() {
    client := currencyapi.Client("YOUR_API_KEY")

    ratesParams := map[string]string{
        "output": "JSON",
        "base":   "USD",
    }

    body, err := client.Rates(ratesParams)
    var response JsonResponse
    if nil != json.Unmarshal(body, &response) {
        fmt.Println("Error parsing JSON: ", err)
        return
    }

    if response.Valid {
        fmt.Printf("1 USD  = %f EUR\n", response.Result["EUR"])
    } else {
        fmt.Printf("API returned error: Code: %d, Message: %s\n", response.Error.Code, response.Error.Message)
    }
}

# Outputs
1 USD  = 0.906285 EUR

Fantastic. Our first live currency rates using Go. The above code fetches the latest exchange rates with USD as the base currency and outputs what the value in EUR is today.

Available Parameters for Rates Endpoint - Go SDK

Parameter	Description
base	Sets the base currency for conversions. This will output all currency conversions for that currency. Default is USD.
output	Specifies the response format: JSON or XML. Default is JSON.

Currency Conversion with GoLang SDK

With our API and Go SDK you can convert currency amounts from one currency to another. This is great for just converting the currencies you need.

The response of the Convert endpoint is slightly different to the Rates endpoint, so we should create a new Struct.

type JsonResponse struct {
    Valid bool `json:"valid"`
    Conversion map[string]interface{} `json:"conversion"`
    Error *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

This Struct targets the conversion key inside the JSON response.

// ... use the same imports from above

type JsonResponse struct {
    Valid bool `json:"valid"`
    Conversion map[string]interface{} `json:"conversion"`
    Error *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

func main() {
    client := currencyapi.Client("YOUR_API_KEY")

    convertParams := map[string]string{
        "output": "JSON",
        "from":   "USD",
        "to":     "GBP",
        "amount": "15.99",
    }

    body, err := client.Convert(convertParams)
    var response JsonResponse
    if nil != json.Unmarshal(body, &response) {
        fmt.Println("Error parsing JSON: ", err)
        return
    }

    if response.Valid {
        fmt.Printf("%f %s  = %f %s\n", response.Conversion["amount"], response.Conversion["from"], response.Conversion["result"], response.Conversion["to"])
    } else {
        fmt.Printf("API returned error: Code: %d, Message: %s\n", response.Error.Code, response.Error.Message)
    }
}

# Outputs
15.990000 USD  = 12.159356 GBP

And there you have it, converted from USD to GBP on the fly using our currency api sdk for Golang.

Available Methods for Convert Endpoint

Parameter	Description
amount	The value of the currency you want to convert from. This should be a number and can contain a decimal place. Required.
from	The currency you want to convert from. This will be a three-letter ISO 4217 currency code. Required.
to	The currency you want to convert to. This will be a three-letter ISO 4217 currency code. Required.
output	Specifies the response format: JSON or XML. Default is JSON.

Accessing Historical Currency Rates in GoLang

Retrieve historical currency rates can be a super useful for tracking the history of various currency conversions.

With each request you supply a given date, in the example format 2019-01-01, and all currency conversions of a given currency are returned.

We can the same style Struct to our Rates endpoint, but we with a small tweak to include the historical date.

// ... use the same imports from above

type JsonResponse struct {
    Valid bool `json:"valid"`
    Date string `json:"date"` // added Date here
    HistoricalRates map[string]interface{} `json:"rates"`
    Error *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

func main() {
    client := currencyapi.Client("YOUR_API_KEY")

    historicalParams := map[string]string{
        "output": "JSON",
        "base":   "GBP",
        "date":   "2019-01-01",
    }

    body, err := client.History(historicalParams)
    var response JsonResponse
    if nil != json.Unmarshal(body, &response) {
        fmt.Println("Error parsing JSON: ", err)
        return
    }

    if response.Valid {
        fmt.Printf("1 GBP  = %f JPY on %s\n", response.HistoricalRates["JPY"], response.Date)
    } else {
        fmt.Printf("API returned error: Code: %d, Message: %s\n", response.Error.Code, response.Error.Message)
    }
}

# Outputs
1 GBP  = 139.875623 JPY on 2019-01-01

It is as simple as that. We have historical data on a wide range of currencies going back to the year 2000!

Available Parameters for Historical Endpoint - Go SDK

Parameter	Description
date	The historical date you wish to receive the currency conversions for. This should be formatted as YYYY-MM-DD. Required.
base	Sets the base currency for conversions. Default is USD.
output	Specifies the response format: JSON or XML. Default is JSON.

Accessing Live Currency Rates Within a Timeframe

If you need to access currency rates between a specific time frame, you can use our timeframe endpoint. This timeframe can be up to a year long.

We are going to need a slightly different Struct for as each day in between the start and end date will supply a different object.

// ... use the same imports from above

type JsonResponse struct {
    Valid     bool    `json:"valid"`
    StartDate string  `json:"start_date"`
    EndDate   string  `json:"end_date"`
    TimeframeRates     map[string]map[string]float64   `json:"rates"`
    Error     *struct {
        Code    int    `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

func main() {
    client := currencyapi.Client("YOUR_API_KEY")

    timeframeParams := map[string]string{
        "output": "JSON",
        "base":   "GBP",
        "start_date": "2019-01-01",
        "end_date": "2019-01-02",
    }

    body, err := client.Timeframe(timeframeParams)
    var response JsonResponse
    if nil != json.Unmarshal(body, &response) {
        fmt.Println("Error parsing JSON: ", err)
        return
    }

    if response.Valid {
        for date, rates := range response.TimeframeRates {
            fmt.Printf("Date: %s\n", date)
            for currency, rate := range rates {
                fmt.Printf("Currency: %s, Rate: %f\n", currency, rate)
            }
        }
    } else {
        fmt.Printf("API returned error: Code: %d, Message: %s\n", response.Error.Code, response.Error.Message)
    }
}

# Outputs
Date: 2019-01-01
Currency: AED, Rate: 3.673105
Currency: AFN, Rate: 68
...
Date: 2019-01-02
Currency: SCR, Rate: 17.389379
Currency: TMT, Rate: 4.463881
...

Available Parameters for Timeframe Endpoint - Go SDK

Parameter	Description
start_date	The start date for the time frame. Format: YYYY-MM-DD. Required.
end_date	The end date for the time frame. Format: YYYY-MM-DD. Required.
base	Sets the base currency for conversions. Default is USD.
output	Specifies the response format: JSON or XML. Default is JSON.

Error Handling In Golang

In Golang, we use the error type to handle errors. This allows us to gracefully handle errors and provide meaningful error messages to the user.

You can see from the examples above, it's not only important to check the error from the API, its also important handle JSON parsing errors and the request itself.

Best Practices using Golang SDK

To optimize your use of the CurrencyApi.net GoLang SDK, consider the following best practices:

• Implement caching to minimize API calls and improve performance.
• Validate API responses to ensure data integrity.
• Store your API key securely using environment variables or a secure configuration file.
• Stay updated with the SDK documentation for new features and updates.
• Always check for errors after making API calls to handle any issues that may arise.