Historical Exchange Rate Data

Retrieve historical, current, and time-series currency exchange rates powered by the European Central Bank (ECB). This Apify actor wraps the Frankfurter API -- a free, open-source exchange rate service -- and delivers clean, structured data across three flexible modes: latest rates, a specific historical date, or a full daily time series over any date range. It covers 30+ world currencies, requires no API key, and runs in seconds. Use it to build forex dashboards, track currency trends, feed financial models, automate cross-border pricing, or archive exchange rate data on a schedule.

---

Why use Historical Exchange Rate Data?

• Authoritative data source -- All rates originate from the European Central Bank's daily reference rates, the same benchmark used by financial institutions across Europe and worldwide.
• Zero authentication overhead -- No API keys, no tokens, no registration. Configure your currencies and dates, then run. The underlying Frankfurter API is completely free for any volume of usage.
• Scheduled archival -- Set up recurring Apify schedules to capture exchange rates daily, weekly, or at any interval. Build a persistent, queryable currency database without writing infrastructure code.
• Cloud-native dataset storage -- Every run stores results in an Apify dataset exportable as JSON, CSV, XML, or Excel. Access it programmatically via the Apify API or download it from the console.
• Pipeline-ready output -- Chain this actor with webhooks, Zapier, Make, Google Sheets, Slack, or other Apify actors to power automated financial workflows end to end.
• Minimal cost -- Runs complete in under 15 seconds on 256 MB of memory. Apify's free tier covers hundreds of runs per month with no third-party API costs.

---

Key features

• Three retrieval modes -- Fetch the latest rates, look up a specific historical date, or generate a full daily time series between any two dates.
• 30+ currencies supported -- All major currencies tracked by the ECB including USD, GBP, JPY, CHF, AUD, CAD, CNY, INR, KRW, SEK, NOK, MXN, BRL, ZAR, TRY, and more.
• Flexible base currency -- Use any supported currency as the base for all conversions. Default is EUR, but you can set it to USD, GBP, or any other supported code.
• Filtered target currencies -- Optionally specify only the currencies you need instead of fetching all 30+. Keeps output focused and datasets compact.
• One record per day -- In timeseries mode, the actor expands the API response into individual daily records, ready for charting, aggregation, or time-series analysis.
• Historical depth back to 1999 -- Query any date from January 4, 1999 (the euro's introduction) through today. Over 25 years of daily ECB reference rates are available.
• Single API call execution -- Each run makes exactly one HTTP request regardless of mode. No pagination, no rate limiting, no retries needed.
• Fast and lightweight -- Typical runs finish in 3 to 10 seconds using 256 MB of memory, consuming a fraction of a compute unit.
• Clean structured output -- Every record includes the base currency code, date, a rates object mapping currencies to numeric values, and an ISO 8601 extraction timestamp.

---

How to use Historical Exchange Rate Data

From the Apify Console

1. Go to the Historical Exchange Rate Data actor page on Apify.
2. Click Start (or Try for free if this is your first run).
3. Set the Base Currency (e.g., USD). Leave blank to default to EUR.
4. Optionally fill in Target Currencies as a comma-separated list (e.g., GBP,JPY,CHF). Leave empty for all currencies.
5. Select a Mode:
   • latest -- Returns today's most recent rates.
   • date -- Returns rates for a specific historical date. Fill in the Date field.
   • timeseries -- Returns daily rates for a range. Fill in Start Date and End Date.
6. Click Start to launch the run.
7. When the run finishes, open the Dataset tab to view, filter, or download results as JSON, CSV, or Excel.

From the Apify API or CLI

apify call ryanclinton/exchange-rate-history \
  --input='{"base":"USD","symbols":"EUR,GBP,JPY","mode":"timeseries","startDate":"2024-06-01","endDate":"2024-06-30"}'

---

Input parameters

Parameter	Type	Required	Default	Description
base	String	No	EUR	Base currency code (ISO 4217). All returned rates are relative to 1 unit of this currency.
symbols	String	No	(all currencies)	Comma-separated target currency codes (e.g., USD,GBP,JPY). Leave empty to retrieve all 30+ supported currencies.
mode	String	No	latest	Retrieval mode. Options: latest, date, or timeseries.
date	String	Conditional	--	Specific date in YYYY-MM-DD format. Required when mode is date.
startDate	String	Conditional	--	Start of the date range in YYYY-MM-DD format. Required when mode is timeseries.
endDate	String	Conditional	--	End of the date range in YYYY-MM-DD format. Required when mode is timeseries.

Input example -- latest rates

{
    "base": "EUR",
    "symbols": "USD,GBP,CHF",
    "mode": "latest"
}

Input example -- specific historical date

{
    "base": "USD",
    "symbols": "EUR,JPY,CAD,AUD",
    "mode": "date",
    "date": "2023-07-15"
}

Input example -- time series

{
    "base": "GBP",
    "symbols": "USD,EUR,JPY",
    "mode": "timeseries",
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
}

Tips

• Always use standard three-letter ISO 4217 currency codes (e.g., USD, not US Dollar).
• The ECB publishes rates on business days only. Weekend and holiday dates are automatically skipped in timeseries mode.
• Historical data is available from January 4, 1999 onward.
• For timeseries mode, a one-month range produces roughly 22 records and a full year produces roughly 260 records (business days only).

---

Output

Each record in the output dataset contains four fields. In latest and date modes, the dataset holds a single record. In timeseries mode, it holds one record per business day in the range.

Output fields

Field	Type	Description
base	String	The base currency code (e.g., USD).
date	String	The date of the rates in YYYY-MM-DD format.
rates	Object	Key-value pairs mapping each target currency code to its exchange rate relative to 1 unit of the base currency.
extractedAt	String	ISO 8601 timestamp of when the data was extracted by the actor.

Output example -- single record (latest or date mode)

{
    "base": "USD",
    "date": "2024-12-05",
    "rates": {
        "EUR": 0.94732,
        "GBP": 0.79145,
        "JPY": 150.283
    },
    "extractedAt": "2024-12-05T14:30:00.000Z"
}

Output example -- time series (one record per day)

[
    {
        "base": "GBP",
        "date": "2024-01-02",
        "rates": {
            "USD": 1.2632,
            "EUR": 1.1538,
            "JPY": 183.421
        },
        "extractedAt": "2024-03-31T10:00:00.000Z"
    },
    {
        "base": "GBP",
        "date": "2024-01-03",
        "rates": {
            "USD": 1.2587,
            "EUR": 1.1502,
            "JPY": 182.956
        },
        "extractedAt": "2024-03-31T10:00:00.000Z"
    },
    {
        "base": "GBP",
        "date": "2024-01-04",
        "rates": {
            "USD": 1.2651,
            "EUR": 1.1564,
            "JPY": 183.712
        },
        "extractedAt": "2024-03-31T10:00:00.000Z"
    }
]

---

Use cases

• Forex trend analysis -- Track how currency pairs like EUR/USD or GBP/JPY have moved over weeks, months, or years to identify patterns and inform trading strategies.
• E-commerce pricing -- Monitor exchange rates to dynamically adjust product prices for international storefronts, ensuring margins stay consistent across currencies.
• Financial reporting -- Automate the retrieval of daily or monthly exchange rates for multi-currency accounting, tax filings, and regulatory compliance.
• Travel cost planning -- Look up historical rates to estimate travel budgets or compare exchange rate trends for upcoming destinations.
• Academic research -- Collect long-running time series data for econometric analysis, macroeconomic studies, or currency volatility research.
• Invoice reconciliation -- Retrieve the exact exchange rate for a specific transaction date to verify cross-border invoices and payment amounts.
• Portfolio valuation -- Convert foreign-denominated investment holdings to your home currency using the official ECB reference rate for accurate portfolio snapshots.
• Supply chain cost tracking -- Monitor currency fluctuations that impact import/export costs and raw material pricing for procurement teams.
• Dashboard and visualization feeds -- Pipe structured daily rate data into BI tools, Grafana, or custom dashboards for real-time currency monitoring.
• Automated alerting -- Schedule daily runs and trigger webhooks or Slack notifications when a currency pair crosses a threshold you define.

---

API & integrations

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("gh3BeaT9qw9MKrdPP").call(run_input={
    "base": "USD",
    "symbols": "EUR,GBP,JPY",
    "mode": "timeseries",
    "startDate": "2024-06-01",
    "endDate": "2024-06-30",
})

dataset = client.dataset(run["defaultDatasetId"])
for item in dataset.iterate_items():
    print(f"{item['date']}: {item['rates']}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("gh3BeaT9qw9MKrdPP").call({
    base: "USD",
    symbols: "EUR,GBP,JPY",
    mode: "timeseries",
    startDate: "2024-06-01",
    endDate: "2024-06-30",
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.log(`${item.date}: ${JSON.stringify(item.rates)}`);
});

cURL

curl "https://api.apify.com/v2/acts/gh3BeaT9qw9MKrdPP/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "base": "USD",
    "symbols": "EUR,GBP",
    "mode": "latest"
  }'

Integrations

• Google Sheets -- Export the dataset directly to a spreadsheet for pivot tables, charting, and financial modeling.
• Zapier / Make -- Trigger automated workflows whenever a new exchange rate dataset is created.
• Webhooks -- Send results to your own API endpoint for custom downstream processing.
• Slack / Email -- Configure notifications to alert you when runs complete or when a rate crosses a threshold.
• Apify Scheduling -- Run the actor on a cron schedule (e.g., every day at 17:00 CET after the ECB publishes new rates).

---

How it works

The actor follows a straightforward pipeline to fetch, transform, and store exchange rate data from the Frankfurter API.

Pipeline steps

1. Parse input -- Read the base currency, target currencies, mode, and date parameters from the actor input.
2. Build API URL -- Construct the Frankfurter API endpoint based on the selected mode:
   • latest mode calls /v1/latest
   • date mode calls /v1/{YYYY-MM-DD}
   • timeseries mode calls /v1/{startDate}..{endDate}
3. Append query parameters -- Add base and optionally symbols (comma-separated) to the URL query string.
4. Execute HTTP request -- Make a single GET request to the Frankfurter API (no authentication required).
5. Transform response -- For latest and date modes, wrap the response into a single output record. For timeseries mode, expand the nested rates object into one flat record per business day.
6. Add metadata -- Attach an extractedAt ISO 8601 timestamp to every record.
7. Push to dataset -- Store all records in the Apify dataset for export and API access.

Architecture

+------------------+       +------------------------+       +------------------+
|   Actor Input    | ----> |   Frankfurter API v1   | ----> |  Apify Dataset   |
| (base, symbols,  |       | api.frankfurter.dev/v1 |       | (JSON/CSV/Excel) |
|  mode, dates)    |       |   (ECB data source)    |       |                  |
+------------------+       +------------------------+       +------------------+
        |                            |                              |
   Parse & build            Single HTTP GET               Push structured
   API request              (no auth needed)              output records

---

Performance & cost

Metric	Latest / Date Mode	Time Series Mode
API calls per run	1	1
Memory allocation	256 MB	256 MB
Typical run time	3 -- 8 seconds	5 -- 15 seconds
Output records	1	~22 per month / ~260 per year
Estimated CU cost	~0.001 CU	~0.002 -- 0.005 CU
Approximate USD cost	< $0.001	< $0.005
Third-party API cost	Free	Free
Rate limiting	None	None

Apify's free tier includes $5 of platform usage per month, which is sufficient for thousands of runs of this actor. Even hourly scheduled runs for an entire month would remain well under $1.

---

Limitations

• Business days only -- The ECB publishes reference rates on business days only. Weekend and public holiday dates are automatically skipped in time series output. No interpolation is performed.
• Daily granularity -- Rates are published once per day around 16:00 CET. Intraday, real-time, or tick-level forex data is not available through this source.
• ECB currency coverage -- Only the 30+ currencies tracked by the European Central Bank are supported. Exotic or less-traded currencies not covered by the ECB are unavailable.
• No cryptocurrency support -- The Frankfurter API covers fiat currencies only. For crypto exchange rates, use a dedicated crypto data actor.
• Historical start date -- Data begins on January 4, 1999 (the euro's introduction date). Dates before this are not available.
• Single base per run -- Each run uses one base currency. To get rates relative to multiple base currencies, run the actor multiple times with different base settings.
• ECB publication delay -- The latest rates reflect the ECB's most recent publication, which may lag the current spot market by several hours.

---

Responsible use

• Non-commercial ECB data -- The European Central Bank's reference rates are published for information purposes. They are not intended as the sole basis for financial transactions. Always verify rates with your bank or broker for actual trades.
• Respect the Frankfurter API -- While the API has no formal rate limits, avoid scheduling runs more frequently than necessary. Once per day after 16:00 CET (when the ECB publishes new rates) is sufficient for most use cases.
• Data accuracy disclaimer -- Exchange rates are provided as-is from the ECB via the Frankfurter API. The actor does not modify, interpolate, or estimate any values. Always cross-reference critical financial data with primary sources.
• Compliance with local regulations -- If you use exchange rate data for accounting, tax, or regulatory reporting, ensure that ECB reference rates meet the requirements of your jurisdiction.
• Fair scheduling -- Use reasonable scheduling intervals. There is no benefit to running more than once per business day since the ECB publishes rates only once daily.

---

FAQ

Q: What currencies are supported? A: All currencies tracked by the European Central Bank, including: USD, GBP, JPY, CHF, AUD, CAD, CNY, HKD, NZD, SEK, KRW, SGD, NOK, MXN, INR, ZAR, TRY, BRL, TWD, DKK, PLN, THB, IDR, HUF, CZK, ILS, CLP, PHP, RON, ISK, MYR, and BGN. Over 30 currencies in total.

Q: Do I need an API key or any authentication? A: No. The Frankfurter API is completely free and requires no API key, token, or registration. The actor works out of the box.

Q: How current is the "latest" data? A: The ECB publishes reference rates around 16:00 CET each business day. The "latest" mode returns the most recently published rates, which may be from the previous business day if queried before the daily publication or on a weekend.

Q: Can I get intraday or real-time forex rates? A: No. The ECB publishes rates once per day. For intraday or real-time data, you would need a dedicated forex data provider or a different actor.

Q: What happens on weekends and holidays? A: In timeseries mode, the actor only returns records for dates when the ECB published rates. Weekends and ECB holidays are automatically skipped -- no empty or duplicate records are generated.

Q: How far back does historical data go? A: Data is available from January 4, 1999, when the euro was introduced and the ECB began publishing daily reference rates. You can query any date from 1999 through today.

Q: Can I use EUR as a target currency? A: Yes, but you must set a different base currency. For example, set base to USD and include EUR in symbols. You cannot use the same currency as both base and target.

Q: How many records does a time series query return? A: Approximately 22 records per month and 260 records per year, since only business days are included. A multi-year query can return thousands of records.

Q: Can I use this for cryptocurrency exchange rates? A: No. The Frankfurter API only covers fiat currencies tracked by the ECB. For cryptocurrency data, use the CoinGecko Crypto Data actor.

Q: What format are the dates in? A: All dates use the YYYY-MM-DD ISO 8601 format, both in the input parameters and in the output records.

Q: Is there a limit on the time series date range? A: There is no hard limit. You can query from 1999-01-04 through today in a single run. However, very long ranges (10+ years) will produce large datasets with thousands of records. The actor handles this in a single API call regardless of range length.

Q: How often should I schedule this actor? A: Once per business day after 16:00 CET is optimal, since that is when the ECB publishes new rates. Running more frequently provides no additional data.

---

Related actors

Actor	Description
Currency Exchange Rate Tracker	Fetch the latest real-time exchange rates from multiple providers. Use this for current rates without historical lookups.
ECB Exchange Rates	Retrieve exchange rates directly from the European Central Bank's data feeds with additional ECB-specific metadata.
World Bank Development Indicators	Access macroeconomic indicators including GDP, inflation, and trade data that correlate with currency movements.
Finnhub Stock Market Data	Pull stock quotes, company financials, and market data. Combine with exchange rates for international portfolio analysis.
CoinGecko Crypto Data	Retrieve cryptocurrency prices, market caps, and exchange rates. Use alongside this actor for both fiat and crypto coverage.