Historical Exchange Rates

On this page, we’ll dive into the historical exchange rates endpoint you can use to retrieve historical exchange rates for a specific date. Data are available all the way back to 1999.

GET/v3/historical

Historical Exchange Rates

This historical exchange rates endpoint provides currency rates for a specified date.

Required attributes

Name
date
Type
string
Description
Date to retrieve historical rates from (format: 2021-12-31)
Name
dates
Type
string
Description
Instead of date: up to 31 dates, comma-separated (2022-01-31,2022-02-28) or as dates[]=2022-01-31&dates[]=2022-02-28 Not together with date, see several dates

Optional attributes

Name
base_currency
Type
string
Description
The base currency to which all results are behaving relative to By default all values are based on USD
Name
currencies
Type
string
Description
A list of comma separated currency codes which you want to get (EUR,USD,CAD) By default all available currencies will be shown
Name
type
Type
string
Description
The type of currency you want to get (fiat, metal or crypto) By default all types will be shown
Name
shape
Type
string
Description
default or compact. With compact every rate is a plain value ("EUR": 0.918456) instead of a code/value object
Name
precision
Type
integer
Description
Round every value to this many decimals (0 to 10) By default values carry up to 10 decimals
Name
inverse
Type
boolean
Description
true adds inverse to every rate: the value of one unit of the currency in the base currency (1 / value) Not together with shape=compact
Name
format
Type
string
Description
json (default), csv or xlsx. The CSV has one row per currency (and date): datetime,base_currency,currency,value, plus inverse with inverse=true xlsx gives the same table as an Excel workbook, see Excel downloads

Response Properties

The response is the same as the response from the /latest endpoint, including the optional representations (without include=change). With date, meta also holds the requested date.

Several dates in one request

With dates instead of date you get up to 31 days in one response. data is then keyed by date, oldest first, and each date is answered once. meta holds the base_currency and the dates answered.

Every date costs one request of your quota, as it would on its own; the X-Cost response header tells you how many were counted.

Month-end rates of two months

curl -G https://api.currencyapi.com/v3/historical \
    -d dates=2022-01-31,2022-02-28 \
    -d currencies=EUR,GBP \
    -d shape=compact \
    -H "apikey: YOUR-API-KEY"

Response (X-Cost: 2)

{
    "meta": {
        "base_currency": "USD",
        "dates": ["2022-01-31", "2022-02-28"]
    },
    "data": {
        "2022-01-31": {
            "EUR": 0.890103,
            "GBP": 0.743712
        },
        "2022-02-28": {
            "EUR": 0.891437,
            "GBP": 0.745601
        }
    }
}

With format=csv the dates follow each other in one table:

Response (text/csv)

datetime,base_currency,currency,value
2022-01-31T23:59:59Z,USD,EUR,0.890103
2022-01-31T23:59:59Z,USD,GBP,0.743712
2022-02-28T23:59:59Z,USD,EUR,0.891437
2022-02-28T23:59:59Z,USD,GBP,0.745601

Request

GET

/v3/historical

curl -G https://api.currencyapi.com/v3/historical \
    -d date=2022-01-01 \
    -H "apikey: YOUR-API-KEY"

Full Response

{
    "meta": {
        "last_updated_at": "2022-01-01T23:59:59Z",
        "base_currency": "USD",
        "date": "2022-01-01"
    },
    "data": {
        "AED": {
            "code": "AED",
            "value": 3.67306
        },
        "AFN": {
            "code": "AFN",
            "value": 91.80254
        },
        "ALL": {
            "code": "ALL",
            "value": 108.22904
        },
        "AMD": {
            "code": "AMD",
            "value": 480.41659
        },
        "...": "180+ more currencies"
    }
}