# Currency Exchange Rates API: Open Exchange Rates (`nabeelbaghoor/currency-exchange-rates-historical-api`) Actor

Currency exchange rates API for 200+ currencies: latest FX rates, historical exchange rates back to 1999, monthly time series, OHLC and average rates, currency conversion and the currency list, through the Open Exchange Rates API. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/currency-exchange-rates-historical-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Integrations
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 exchange rate for one currency and dates

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Currency Exchange Rates API: Open Exchange Rates

Get latest and historical currency exchange rates for 200+ currencies, daily FX time series, OHLC and average rates and currency conversions from Open Exchange Rates with your own App ID, as clean rows you can export to CSV, Excel or JSON.

Open Exchange Rates (Open Exchange Rates (UK) Ltd) is a foreign exchange rate data service used by startups, ecommerce stores, accounting tools and finance teams. This actor wraps the read endpoints of the Open Exchange Rates API: latest rates, historical rates back to 1 January 1999, the time series and OHLC endpoints, the convert endpoint, the currency list and your App ID's usage. Use it for multi currency pricing, invoice and accounting conversions, treasury and FX reporting, BI pipelines, spreadsheets and backtesting. Bring your own API key.

BYOK, not live tested: every route, parameter and response field comes from Open Exchange Rates' own API documentation (docs.openexchangerates.org), and every route was probed on 2026-11-01 with an invalid App ID. The actor has not been run against a live App ID.

### What it does

- **Latest exchange rates**: the most recent rates available on your plan (the usage mode shows its update frequency) for every currency, or just the codes you list, against USD or another base.
- **Historical exchange rates**: end of day rates (the last values published each UTC day) for any list of dates or a whole date range, back to 1999-01-01.
- **Exchange rate time series**: daily rates over a range, requested one calendar month at a time as the API requires (Enterprise and Unlimited plans).
- **OHLC and average rates**: open, high, low, close and time weighted average rates for periods from 1 minute to 1 month (VIP Platinum plan).
- **Currency conversion**: convert any amount between two currencies at the latest rate (Unlimited plan).
- **Currency list**: every currency code with its full name, optionally with alternative, digital and inactive currencies. Needs no key and is free.
- **Usage and plan**: your plan name, update frequency, enabled features and requests used and remaining this month. Free.
- **Two row layouts** for rate modes: one flat row per currency and date with rate and inverse rate, or one row per date holding every rate.
- **Plan aware**: features your plan lacks end the run cleanly with a message naming the plan that has them, and a historical request whose symbols filter your plan refuses is retried without it and filtered by the actor.
- **Read only and pay only for results**: empty answers and refused lookups become a free row that says why.

### How to get your own key

1. Sign up at openexchangerates.org/signup. The free plan covers latest and historical rates with USD as base; paid plans add base currency changes, time series, OHLC and conversion.
2. Copy your App ID from openexchangerates.org/account/app-ids.
3. Paste it into the **Open Exchange Rates App ID** field, or set the DATA_API_KEY environment secret. The actor sends it in the documented `Authorization: Token` header.
4. Run the **Usage and plan** mode first to see which features your App ID includes.

### Input

| Field | Modes | Notes |
| --- | --- | --- |
| `mode` | all | `latest`, `historical`, `timeSeries`, `ohlc`, `convert`, `currencies`, `usage` |
| `apiKey` | all but currencies | your App ID; falls back to the DATA_API_KEY secret |
| `base` | rate modes, ohlc | 3 letter base code, default USD (other bases need a paid plan) |
| `symbols` | rate modes, ohlc | codes to return, such as EUR, GBP, JPY; empty for all |
| `showAlternative` | rate modes, ohlc, currencies | add alternative and digital currencies |
| `dates` | historical | one YYYY-MM-DD per line, from 1999-01-01 |
| `startDate`, `endDate` | historical, timeSeries | inclusive range; historical reads every day (up to 1,000), the time series one month per request |
| `startTimes` | ohlc | one YYYY-MM-DDThh:mm:00Z per line, on or after 2016-12-19 |
| `period` | ohlc | `1m`, `5m`, `15m`, `30m`, `1h`, `12h`, `1d`, `1w`, `1mo` |
| `conversions` | convert | one `amount FROM TO` per line, such as `100 GBP EUR` |
| `showInactive` | currencies | add inactive currencies |
| `rowLayout` | rate modes | `pairs` (one row per currency and date) or `snapshots` (one row per date) |
| `maxResults` | all | stop after this many rows (default 1,000) |

### Output

A rate row in the pairs layout:

```json
{
    "mode": "historical",
    "recordType": "rate",
    "query": "2024-01-31",
    "found": true,
    "date": "2024-01-31",
    "timestamp": 1706745599,
    "publishedAt": "2024-01-31T23:59:59.000Z",
    "base": "USD",
    "currency": "EUR",
    "currencyName": "Euro",
    "rate": 0.924712,
    "inverseRate": 1.0814178857
}
```

An OHLC row:

```json
{
    "mode": "ohlc",
    "recordType": "ohlc",
    "query": "2024-01-02T00:00:00Z 1d",
    "found": true,
    "startTime": "2024-01-02T00:00:00Z",
    "endTime": "2024-01-02T23:59:59Z",
    "period": "1d",
    "base": "USD",
    "currency": "GBP",
    "currencyName": "British Pound Sterling",
    "open": 0.78566,
    "high": 0.79265,
    "low": 0.78453,
    "close": 0.79171,
    "average": 0.78897
}
```

Snapshot rows carry `date`, `base`, `currencyCount` and a `rates` object; conversion rows carry `from`, `to`, `amount`, `rate`, `converted` and `publishedAt`; currency rows carry `currency` and `currencyName`; the usage row carries `planName`, `quota`, `updateFrequency`, `features`, `requests`, `requestsQuota` and `requestsRemaining` (the App ID itself is never written). The values above are illustrative.

### Pricing

Pay per event, only for rows with data:

| Event | Price |
| --- | --- |
| Exchange rate (one currency and date, pairs layout) | $0.005 |
| Rate snapshot (one date with every requested rate) | $0.02 |
| OHLC bar (one currency and period) | $0.01 |
| Currency conversion | $0.005 |
| Currency list and usage rows | free |

Your Open Exchange Rates plan is billed separately by Open Exchange Rates. Each historical date and each time series day counts as one request against your monthly allowance; the currency list and usage calls do not count. With many currencies, the snapshots layout or a short symbols list keeps the cost down.

### FAQ

#### What is the Open Exchange Rates API?

The Open Exchange Rates API is a JSON foreign exchange rate API run by Open Exchange Rates (UK) Ltd. It publishes midpoint exchange rates for 200+ world, alternative and digital currencies, with latest, historical (from 1999), time series, OHLC and conversion endpoints.

#### Do I need my own Open Exchange Rates App ID?

Yes for every mode except the currency list. This actor is bring your own key: your App ID, your plan and your monthly request allowance. A free App ID covers latest and historical rates against USD.

#### Why did my run stop with "not on your plan"?

Open Exchange Rates gates some features by plan: changing the base currency needs a paid plan, symbols on historical rates need the Developer plan or above, the time series needs Enterprise or Unlimited, convert needs Unlimited and OHLC needs VIP Platinum. The run ends cleanly and says which plan has the feature. The usage and plan mode shows your features.

#### How far back do historical exchange rates go?

To 1 January 1999. Each date returns the last rates published that UTC day; a request for today's UTC date returns the latest rates instead.

#### Are these mid market rates?

Yes. The Open Exchange Rates documentation describes its values as midpoint rates. They are reference rates for information, not dealing quotes, and Open Exchange Rates gives no warranty for transactional use.

#### How is this different from other exchange rate actors?

It calls the official Open Exchange Rates API with your own App ID, so you get the provider's own data under your own plan, every documented read endpoint, plan aware error handling and flat rows with inverse rates and currency names.

#### What do I pay?

$0.005 per exchange rate row or conversion, $0.01 per OHLC bar and $0.02 per one row per date snapshot. The currency list, the usage row, empty answers and refused lookups are free.

### Keyword map

currency exchange rates API, historical exchange rates, FX rates API, foreign exchange rates, exchange rate time series, OHLC exchange rates, currency converter API, Open Exchange Rates, openexchangerates.org, USD EUR GBP JPY rates, currency list, forex data.

### Routes and verification

| Mode | Route | Probe with invalid App ID (twice) |
| --- | --- | --- |
| Latest rates | GET /api/latest.json | 401 JSON invalid_app_id (query and Authorization header) |
| Historical rates | GET /api/historical/{date}.json | 401 JSON invalid_app_id |
| Time series | GET /api/time-series.json | 401 JSON invalid_app_id |
| OHLC | GET /api/ohlc.json | 401 JSON invalid_app_id |
| Convert | GET /api/convert/{value}/{from}/{to} | 401 JSON invalid_app_id |
| Usage | GET /api/usage.json | 401 JSON invalid_app_id |
| Currency list | GET /api/currencies.json | 200 JSON without a key, as documented |
| Invented control routes | GET /api/spot-rates.json, /api/historical-range.json | 405 text/plain Method Not Allowed |

Every keyed request sends the App ID in the documented `Authorization: Token` header, never in a URL or a log line. The currency list is called without the key.

### Licensing and data use

This actor works only with your own Open Exchange Rates App ID, and your agreement with Open Exchange Rates applies: the Terms and Conditions of Website Use, the Acceptable Use Policy and, for paid plans, the Services Agreement. The Services Agreement licenses the data for reasonable use under those terms and sets no cache or retention limit. The terms say you must not profit directly from selling or providing the information or resell access without a licence from Open Exchange Rates, ask you to keep your App ID confidential, and state that consumer (non business) users get the site for domestic and private use only. Use the rates in your own products and reporting and do not resell the raw data. This actor is not affiliated with or endorsed by Open Exchange Rates.

# Actor input Schema

## `mode` (type: `string`):

Each mode calls one documented read endpoint of the Open Exchange Rates API. Latest and historical rates work on every plan, including free; time series, OHLC and conversion need the paid plans named below, and the currency list needs no key at all.

## `apiKey` (type: `string`):

Your own App ID from openexchangerates.org/account/app-ids (a free plan exists). Sent in the Authorization header, never in a URL. Leave empty to use the DATA_API_KEY secret. Not needed for the currency list.

## `base` (type: `string`):

Latest, historical, time series and OHLC. The 3 letter code every rate is quoted against. USD is the default and works on every plan; any other base needs a paid plan.

## `symbols` (type: `array`):

Latest, historical, time series and OHLC. Limit the answer to these codes (such as EUR, GBP, JPY, BTC). Leave empty for every currency. If your plan does not allow this filter on historical rates, the actor reads all rates and filters them itself.

## `showAlternative` (type: `boolean`):

Latest, historical, time series, OHLC and currency list. Adds the unofficial, black market and digital currency rates Open Exchange Rates publishes (show_alternative).

## `dates` (type: `array`):

Historical rates. One date per line as YYYY-MM-DD (UTC), from 1999-01-01. Each date is one request and returns the last rates published that UTC day.

## `startDate` (type: `string`):

Historical rates and time series. First day of a range as YYYY-MM-DD. Historical rates read every day of the range (up to 1,000 days); the time series reads it in calendar month requests, as the API allows one month per request.

## `endDate` (type: `string`):

Historical rates and time series. Last day of the range as YYYY-MM-DD, inclusive. Defaults to today (UTC).

## `startTimes` (type: `array`):

OHLC. One start time per line as YYYY-MM-DDThh:mm:00Z (UTC, zero seconds), on or after 2016-12-19. The API limits how far back short periods may start: 1m within the past hour, 5m and 15m within 24 hours, 30m and 1h within 32 days.

## `period` (type: `string`):

OHLC. The length of each bar starting at the start time. 1w must start at midnight and 1mo on the first of a month; the period must already be complete.

## `conversions` (type: `array`):

Currency conversion. One conversion per line as amount, from code and to code, such as 100 GBP EUR or 19999.95 USD JPY. Uses the latest rates.

## `showInactive` (type: `boolean`):

Currency list. Also list historical and inactive currencies (show_inactive).

## `rowLayout` (type: `string`):

Latest, historical and time series. Pairs gives flat columns that are easy to filter and chart; snapshots keeps each date in one row, cheaper when you want many currencies.

## `maxResults` (type: `integer`):

The run stops after this many rows.

## Actor input object example

```json
{
  "mode": "latest",
  "base": "USD",
  "symbols": [
    "EUR",
    "GBP",
    "JPY",
    "CAD",
    "AUD"
  ],
  "showAlternative": false,
  "period": "1d",
  "showInactive": false,
  "rowLayout": "pairs",
  "maxResults": 1000
}
```

# Actor output Schema

## `records` (type: `string`):

One row per rate, snapshot, OHLC bar, conversion, currency or usage record the chosen mode read.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "symbols": [
        "EUR",
        "GBP",
        "JPY",
        "CAD",
        "AUD"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/currency-exchange-rates-historical-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "symbols": [
        "EUR",
        "GBP",
        "JPY",
        "CAD",
        "AUD",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/currency-exchange-rates-historical-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "symbols": [
    "EUR",
    "GBP",
    "JPY",
    "CAD",
    "AUD"
  ]
}' |
apify call nabeelbaghoor/currency-exchange-rates-historical-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/currency-exchange-rates-historical-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XlmmahYmpaAHDmgce/builds/KfIRkczf1cgGY6prq/openapi.json
