# ECB Exchange Rates + Invoice Converter by Date (`oatpage/ecb-exchange-rates`) Actor

Official European Central Bank euro reference rates for 40+ currencies. Pick currencies and a date range, or just the latest rate. Clean JSON with inverse rates. No login, no proxy.

- **URL**: https://apify.com/oatpage/ecb-exchange-rates.md
- **Developed by:** [Oatpage](https://apify.com/oatpage) (community)
- **Categories:** Business, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 exchange rates

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

## ECB Euro Exchange Rates

Independent tool. Not an official service and not endorsed by the European Central Bank. Daily euro foreign exchange reference rates published by the ECB (about 40 currencies, history since 1999), returned as clean JSON.

**Data source:** European Central Bank, euro foreign exchange reference rates (ECB Data Portal, data-api.ecb.europa.eu). The ECB allows reuse of its statistics provided the source is acknowledged. The actor only filters and structures the data; it does not change any rate. The ECB indicates that reference rates are for information purposes only and are not intended for transaction purposes.

### Invoice converter (batch)

Send a list of lines and get each amount converted with the ECB reference rate **of that date**, or, when nothing was published that day (weekends, TARGET holidays), **the last rate published before it**. Every result says which rate date was used, so you can show it in your books.

Input (`conversions`):

```json
[{"date":"2026-10-11","from":"USD","to":"EUR","amount":1200},
 {"date":"2025-12-27","from":"GBP","to":"USD","amount":100}]
```

Output (real run):

```json
{"type":"conversion","date":"2026-10-11","from":"USD","to":"EUR","amount":1200,"base":"EUR","rate":0.89237908,"rateDate":"2026-10-09","daysBack":2,"usedEarlierRate":true,"convertedAmount":1070.85}
{"type":"conversion","date":"2025-12-27","from":"GBP","to":"USD","amount":100,"base":"EUR","rate":1.3503265,"rateDate":"2025-12-24","daysBack":3,"usedEarlierRate":true,"convertedAmount":135.03}
```

- Any pair works: rates go through the euro (`rate` = units of `to` per 1 `from`); `EUR` can be either side.
- One request to the ECB serves the whole batch (up to 10,000 lines).
- A line with no published rate on or before its date (before 1999 or before a currency started) comes back with `error: "no_rate_published_on_or_before_date"` and is **not billed**.
- Billing: one `rate` event per converted line. Informational only: check with your accountant which rate and date your jurisdiction requires.

### Input

| Field | Meaning | Default |
|---|---|---|
| `currencies` | 3-letter codes (`USD`, `GBP`, `JPY`...); empty = all | `USD`, `GBP` |
| `startDate`, `endDate` | Range in `YYYY-MM-DD` | none |
| `conversions` | Batch of `{date, from, to, amount}` lines (see above); when present, the fields below are ignored | none |
| `latestOnly` | Only the latest rate per currency | `false` |
| `maxItems` | 1-100,000 rates, newest first | 100 |

### Output (one record per currency and day)

```json
{"date":"2026-10-09","currency":"JPY","currencyName":"Japanese yen","base":"EUR","rate":177.34,"inverseRate":0.00563889,"source":"European Central Bank, ECB euro foreign exchange reference rates","fetchedAt":"2026-10-10T18:47:22.868Z"}
```

`rate` = units of the currency per 1 EUR. `inverseRate` = EUR per 1 unit (calculated).

### Pricing (pay per event)

- Run start: $0.005
- Rate: $0.0005 (one year of one currency, about 250 days = $0.125)

### Limits

- Rates are published on TARGET working days around 16:00 CET; weekends and holidays have no value.
- Reference rates against the euro only; other pairs must be computed by you.
- Not for trading or settlement.

### Data protection

Only public macro-financial data. No personal data.

# Actor input Schema

## `currencies` (type: `array`):

3-letter ISO codes such as USD, GBP, JPY, CHF. Empty list = every currency the ECB publishes.

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

First day to include, format YYYY-MM-DD. Leave empty to get only the most recent publication when 'Latest only' is on, or the full history otherwise.

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

Last day to include, format YYYY-MM-DD. Empty = up to the latest published day.

## `latestOnly` (type: `boolean`):

If on, returns only the most recent rate of each currency and ignores the dates.

## `maxItems` (type: `integer`):

Maximum number of daily rates to return, newest first (rates mode only). Each rate is billed as one event.

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

Optional. A list of {"date":"YYYY-MM-DD","from":"USD","to":"EUR","amount":100}. For each item you get the converted amount using the ECB reference rate of that date or, if none was published that day (weekend, holiday), the last one published before it, plus the date of the rate actually used. When this list is not empty the other fields are ignored. Items without any earlier rate are returned with an error and are not billed.

## Actor input object example

```json
{
  "currencies": [
    "USD",
    "GBP"
  ],
  "latestOnly": false,
  "maxItems": 100,
  "conversions": [
    {
      "date": "2026-10-11",
      "from": "USD",
      "to": "EUR",
      "amount": 1200
    },
    {
      "date": "2026-09-30",
      "from": "EUR",
      "to": "GBP",
      "amount": 500
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "currencies": [
        "USD",
        "GBP"
    ],
    "conversions": [
        {
            "date": "2026-10-11",
            "from": "USD",
            "to": "EUR",
            "amount": 1200
        },
        {
            "date": "2026-09-30",
            "from": "EUR",
            "to": "GBP",
            "amount": 500
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("oatpage/ecb-exchange-rates").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 = {
    "currencies": [
        "USD",
        "GBP",
    ],
    "conversions": [
        {
            "date": "2026-10-11",
            "from": "USD",
            "to": "EUR",
            "amount": 1200,
        },
        {
            "date": "2026-09-30",
            "from": "EUR",
            "to": "GBP",
            "amount": 500,
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("oatpage/ecb-exchange-rates").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 '{
  "currencies": [
    "USD",
    "GBP"
  ],
  "conversions": [
    {
      "date": "2026-10-11",
      "from": "USD",
      "to": "EUR",
      "amount": 1200
    },
    {
      "date": "2026-09-30",
      "from": "EUR",
      "to": "GBP",
      "amount": 500
    }
  ]
}' |
apify call oatpage/ecb-exchange-rates --silent --output-dataset

```

## MCP server setup

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

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/tGqXdffsZA9FSUS26/builds/sasiFzvao8x2GnFYR/openapi.json