Available in plans >= medium

Range Historical Exchange Rates

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

Depending on your subscription plan you can request different accuracies: day, hour, quarter_hour, minute. The coarse accuracies week and month are available on every plan with the range endpoint. Requesting an accuracy your plan does not include returns a 403: "You are not allowed to use the accuracy: ...". Some plans are also limited to a single target currency per request — on those plans, set currencies to exactly one code, otherwise the API responds with a 403: "You are not allowed to request more than one currency".

GET/v3/range

Range Historical Exchange Rates

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

Required attributes

Name
datetime_start
Type
string
Description
Datetime for the start of your requested range (format: 2022-12-01T00:00:00Z / ISO8601 Datetime)
Name
datetime_end
Type
string
Description
️ Datetime for the end of your requested range (format: 2022-12-31T23:59:59Z / ISO8601 Datetime)

Optional attributes

Name
accuracy
Type
string
Description
The accuracy you want to receive. Possible Values: day, hour, quarter_hour, minute, week, month Default: day For valid time ranges see below
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
orient
Type
string
Description
datetime (default): one point per datetime, as shown on this page currency: one series per currency, keyed by currency code ("EUR": [{"datetime": ..., "value": ...}]), see series per currency
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; with orient=currency every point is [datetime, value]
Name
precision
Type
integer
Description
Round every value to this many decimals (0 to 10) By default values carry up to 10 decimals
Name
format
Type
string
Description
json (default), csv or xlsx. The CSV has one row per point in time and currency: datetime,base_currency,currency,value. xlsx gives the same table as an Excel workbook, see Excel downloads

Valid Accuracy Time Ranges

Name
day
Type
Description
- not more than 366 days between start and end
- unlimited look-back (data available back to 1999)
Name
hour
Type
Description
- not more than 7 days between start and end
- not more than 3 months back
Name
quarter_hour
Type
Description
- not more than 24 hours between start and end
- not more than 7 days back
Name
minute
Type
Description
- not more than 6 hours between start and end
- not more than 7 days back
Name
week
Type
Description
- the daily rate at the end of each week (Sunday)
- not more than 1830 days between start and end
Name
month
Type
Description
- the daily rate at the end of each month
- any span, back to 1999

With week and month the last point is datetime_end itself when it falls inside a period, so the newest rate is never dropped. Twenty-five years of month-end rates fit into a single request. For the average of each month instead of its last rate, use /average.

Response Properties

The API response comes with an easy-to-read JSON format and contains currency pairs for all supported world currencies.

The JSON response consists of a meta and a data key. The meta echoes the base_currency, the accuracy (day when you did not request one) and the requested datetime_start and datetime_end.

The datetime in each object holds the datetime when the entry was last updated. Daily accuracy would result in end-of-day values and accuracy of an hour would result in end-of-hour values, and so on.

Month-end rates as CSV

curl -G https://api.currencyapi.com/v3/range \
    -d datetime_start=2025-01-01T00:00:00Z \
    -d datetime_end=2025-12-31T23:59:59Z \
    -d accuracy=month \
    -d currencies=EUR \
    -d format=csv \
    -H "apikey: YOUR-API-KEY"

Response (text/csv)

datetime,base_currency,currency,value
2025-01-31T23:59:59Z,USD,EUR,0.9632
2025-02-28T23:59:59Z,USD,EUR,0.9614
...
2025-12-31T23:59:59Z,USD,EUR,0.8513

Excel downloads

Every endpoint that offers format=csv also offers format=xlsx: the same table as an Excel workbook, ready to open in Excel, Numbers or LibreOffice without an import step. The workbook has one sheet with the CSV’s header as a bold, frozen first row, and the rates are stored as numbers, not text, so you can sort, sum and chart them right away. It comes as a download (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) named after the endpoint, e.g. range.xlsx, latest.xlsx or official-range.xlsx, and costs the same as the CSV.

Month-end rates as an Excel workbook

curl -G https://api.currencyapi.com/v3/range \
    -d datetime_start=2025-01-01T00:00:00Z \
    -d datetime_end=2025-12-31T23:59:59Z \
    -d accuracy=month \
    -d currencies=EUR \
    -d format=xlsx \
    -H "apikey: YOUR-API-KEY" \
    -o range.xlsx

Series per currency

Charts and spreadsheets usually want one series per currency. With orient=currency, data holds one list per currency, oldest point first:

One series per currency

curl -G https://api.currencyapi.com/v3/range \
    -d datetime_start=2022-01-01T00:00:00Z \
    -d datetime_end=2022-01-02T23:59:59Z \
    -d currencies=EUR,GBP \
    -d orient=currency \
    -H "apikey: YOUR-API-KEY"

Response

{
    "meta": {
        "base_currency": "USD",
        "accuracy": "day",
        "datetime_start": "2022-01-01T00:00:00Z",
        "datetime_end": "2022-01-02T23:59:59Z"
    },
    "data": {
        "EUR": [
            {"datetime": "2022-01-01T23:59:59Z", "value": 0.879395},
            {"datetime": "2022-01-02T23:59:59Z", "value": 0.880112}
        ],
        "GBP": [
            {"datetime": "2022-01-01T23:59:59Z", "value": 0.739371},
            {"datetime": "2022-01-02T23:59:59Z", "value": 0.739812}
        ]
    }
}

Add shape=compact and every point becomes a [datetime, value] pair; with precision=4:

Response with shape=compact&precision=4

{
    "meta": {
        "base_currency": "USD",
        "accuracy": "day",
        "datetime_start": "2022-01-01T00:00:00Z",
        "datetime_end": "2022-01-02T23:59:59Z"
    },
    "data": {
        "EUR": [
            ["2022-01-01T23:59:59Z", 0.8794],
            ["2022-01-02T23:59:59Z", 0.8801]
        ],
        "GBP": [
            ["2022-01-01T23:59:59Z", 0.7394],
            ["2022-01-02T23:59:59Z", 0.7398]
        ]
    }
}

Request

GET

/v3/range

curl -G "https://api.currencyapi.com/v3/range?datetime_start=2021-11-30T23:59:59Z&datetime_end=2021-12-31T23:59:59Z&accuracy=day" \
    -H "apikey: YOUR-API-KEY"

Full Response

{
    "meta": {
        "base_currency": "USD",
        "accuracy": "day",
        "datetime_start": "2021-11-30T23:59:59Z",
        "datetime_end": "2021-12-31T23:59:59Z"
    },
    "data": [
        {
            "datetime": "2022-01-01T23:59:59Z",
            "currencies": {
                "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"
            }
        },
        {
            "datetime": "2022-01-02T23:59:59Z",
            "currencies": {
                "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"
            }
        },
        {
            "datetime": "2022-01-03T23:59:59Z",
            "currencies": {
                "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"
            }
        }
    ]
}

`meta` Response Properties

Available in plans >= medium

Name
base_currency
Type
string
Description
The base currency of the values
Name
accuracy
Type
string
Description
The accuracy of the points (day when none was requested)
Name
datetime_start
Type
string
Description
The requested start of the range as a datetime string
Name
datetime_end
Type
string
Description
The requested end of the range as a datetime string

{
    "meta": {
        "base_currency": "USD",
        "accuracy": "day",
        "datetime_start": "2022-01-01T00:00:00Z",
        "datetime_end": "2022-01-31T23:59:59Z"
    }
}

`data` Response Properties

Available in plans >= medium

Name
datetime
Type
string
Description
The date as a datetime string
Name
currencies
Type
object
Description
a list of supported currencies can be retrieved by calling the /currencies endpoint
Name
currencies.code
Type
string
Description
the currency code
Name
currencies.value
Type
float
Description
the current conversion rate

"data": [
    {
        "datetime": "2022-01-01T23:59:59Z",
        "currencies": {
            "AED": {
                "code": "AED",
                "value": 3.67306
            },
            "AFN": {
                "code": "AFN",
                "value": 91.80254
            },
        }
    },
    ...
]

Range Historical Exchange Rates

Range Historical Exchange Rates

Required attributes

Optional attributes

Valid Accuracy Time Ranges

Response Properties

Month-end rates as CSV

Response (text/csv)

Excel downloads

Month-end rates as an Excel workbook

Series per currency

One series per currency

Response

Response with shape=compact&precision=4

Request

Full Response

meta Response Properties

data Response Properties

`meta` Response Properties

`data` Response Properties