Historical Data Requests

Documentation for the Historical Data ExchangeRate-API endpoint.

Overview

Our Historical Exchange Rates API endpoint lets you fetch all the exchange rate data we have available for a specific day in the past. It's only available to users on our Pro, Business or Volume plans.

There are two distinct data sets used by the endpoint.

From 1 January 2021 onwards we have data for our entire list of supported currencies available.

From 1 January 1990 to 31 December 2020 we offer data for the following smaller list of currency codes:

AUD ATS BEF BRL CAD CHF CNY DEM
DKK ESP EUR FIM FRF GBP GRD HKD
IEP INR IRR ITL JPY KRW LKR MXN
MYR NOK NLG NZD PTE SEK SGD THB
TWD USD ZAR

Important Notes
  • We blend data from different sources to reduce inaccuracies & provide one indicative mid-rate for each calendar day. This data is suitable for reporting, dashboards, academic studies, spreadsheets, market insights etc. but shouldn't be used for processing cross-currency settlements or backtesting day trading models. For these you should use the rates supplied by the banks involved in your planned transactions or the historical spread & price data from the markets you plan to trade in.
  • Historical exchange rates are only accessible by paid accounts.
  • Data for some currencies is only available for certain time periods - for instance a number of currencies were replaced with the Euro from 1999 onwards.

Usage Guide - Basic Format

To use our Historical Exchange Rates endpoint you'll need to make the substitutions explained below and then send a GET request.

• Substitute `YOUR-API-KEY` with the API key displayed in your dashboard.

• Substitute `USD` with the code you want to use as a base currency.

• Substitute `YEAR` with the year you'd like data for.

• Substitute `MONTH` with the month you'd like data for (no leading zeros).

• Substitute `DAY` with the day you'd like data for (no leading zeros).

We use ISO 4217 Three Letter Currency Codes - e.g. USD for US Dollars, EUR for Euro etc. Here are the codes we support.

GET https://v6.exchangerate-api.com/v6/YOUR-API-KEY/history/USD/YEAR/MONTH/DAY

This will return all the exchange rates we have data for on the date in question, in terms of the currency you supplied as the base currency:

{
	"result":"success",
	"documentation":"https://www.exchangerate-api.com/docs",
	"terms_of_use":"https://www.exchangerate-api.com/terms",
	"year":2015,
	"month":2,
	"day":22,
	"base_code":"USD",
	"conversion_rates":{
		"AUD":1.4196,
		"BRL":4.0003,
		"CAD":1.324,
		"CHF":0.9744,
		"CNY":6.3559,
		"DKK":6.6601,
		"EUR":0.8929,
		"GBP":0.6595,
		"HKD":7.75,
		"INR":65.57,
		"JPY":119.58,
		"KRW":118,
		....
	}
}

Usage Guide - Specific Pair Conversion Format

• Substitute `YOUR-API-KEY` with the API key displayed in your dashboard.

• Substitute `USD` with the code you want to use as a base currency.

• Substitute `YEAR` with the year you'd like data for.

• Substitute `MONTH` with the month you'd like data for (no leading zeros).

• Substitute `DAY` with the day you'd like data for (no leading zeros).

• Substitute `AMOUNT` with a decimal amount you would like converted.

We use ISO 4217 Three Letter Currency Codes - e.g. USD for US Dollars, EUR for Euro etc. Here are the codes we support.

GET https://v6.exchangerate-api.com/v6/YOUR-API-KEY/history/USD/YEAR/MONTH/DAY/AMOUNT

The returned JSON will include your supplied base currency amount in terms of all the other currencies that we have data available for on your requested date:

{
	"result":"success",
	"documentation":"https://www.exchangerate-api.com/docs",
	"terms_of_use":"https://www.exchangerate-api.com/terms",
	"year":2015,
	"month":2,
	"day":22,
	"base_code":"USD",
	"requested_amount":4.00,
	"conversion_amounts":{
		"AUD":5.664,
		"BRL":16.0012,
		"CAD":5.296,
		"CHF":3.8976,
		"CNY":25.4236,
		"DKK":26.6404,
		"EUR":3.5716,
		"GBP":2.638,
		"HKD":31,
		"INR":262.28,
		"JPY":478.32,
		"KRW":472,
		....
	}
}

Error Responses

{
	"result": "error",
	"error-type": "unknown-code"
}

Where "error-type" can be any of the following:

  • "no-data-available" is returned when our database doesn't have any exchange rates for the specific date you supplied.
  • "unsupported-code" if we don't support the supplied currency code (see supported currencies...).
  • "malformed-request" when some part of your request doesn't follow the structure shown above.
  • "invalid-key" when your API key is not valid.
  • "inactive-account" if your email address wasn't confirmed.
  • "quota-reached" when your account has reached the the number of requests allowed by your plan.
  • "plan-upgrade-required" if your plan level doesn't support this type of request.

➡️️​ If you have any questions about this documentation please contact us!