fxapi Documentation

# Range Historical Exchange Rates

Returns a range of exchange rates. Generally, we provide data going back to 1999.

Switching Accuracy

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.

Plan required

The range endpoint is not part of every plan. Depending on your plan you may also receive a 403 status code when

  • your plan does not include the range endpoint at all,
  • you request an accuracy that is above your plan (e.g. You are not allowed to use the accuracy: minute), or
  • your plan limits range requests to a single currency and you request more than one (You are not allowed to request more than one currency).
{
    "message": "You are not allowed to use the range endpoint, please upgrade your plan",
    "info": "For more information, see documentation: https://fxapi.com/docs/status-codes#_403"
}

To lift these limits please upgrade your plan (opens new window).

Request Method: GET
Request URL: https://api.fxapi.com/v1/range

# Request Parameters

Parameter Type Mandatory Description
apikey string ️ Your API Key
datetime_start string ️ Datetime for the start of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)
datetime_end string ️ Datetime for the end of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)
accuracy string The accuracy you want to receive.
Possible Values: day, hour, quarter_hour, minute, week, month
Default: day
For valid time ranges see below
base_currency string The base currency to which all results are behaving relative to
By default all values are based on USD
currencies string A list of comma-separated currency codes which you want to get (EUR,USD,CAD)
The array form currencies[]=EUR&currencies[]=USD is also accepted
By default all available currencies will be shown
type string Filter the returned currencies by type
Possible Values: fiat, metal, crypto
By default currencies of all types are returned
orient string datetime (default): one point per datetime
currency: one series per currency, keyed by currency code, see series per currency
shape string 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]
precision integer Round every value to this many decimals (0 to 10)
By default values carry up to 10 decimals
format string 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

# day

  • not more than 366 days between start and end (you can go back as far as 1999)

# hour

  • not more than 7 days between start and end
  • not more than 3 months back

# quarter_hour

  • not more than 24 hours between start and end
  • not more than 7 days back

# minute

  • not more than 6 hours between start and end
  • not more than 7 days back

# week

  • the daily rate at the end of each week (Sunday)
  • not more than 1830 days between start and end

# month

  • 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. For the average of each month instead of its last rate, use /average (opens new window).

# Sample Response

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

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.

curl -G https://api.fxapi.com/v1/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"

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

The default JSON response (here for datetime_start=2022-01-01T00:00:00Z&datetime_end=2022-01-03T23:59:59Z) looks like this. The meta key holds:

Attribute Description
base_currency The base currency of the values
accuracy The accuracy of the points (day when none was requested)
datetime_start The requested start of the range as an ISO 8601 datetime
datetime_end The requested end of the range as an ISO 8601 datetime
{
    "meta": {
        "base_currency": "USD",
        "accuracy": "day",
        "datetime_start": "2022-01-01T00:00:00Z",
        "datetime_end": "2022-01-03T23: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
                },
                "...": "150+ 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
                },
                "...": "150+ 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
                },
                "...": "150+ more currencies"
            }
        }
    ]
}

# 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 or latest.xlsx, and costs the same as the CSV.

curl -G https://api.fxapi.com/v1/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:

curl -G https://api.fxapi.com/v1/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"

{
    "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:

{
    "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]
        ]
    }
}

← OHLC Candles →