frankfurter

# Frankfurter

[Frankfurter](https://frankfurter.dev) is a free, open-source exchange rate API for [over 200 currencies](https://frankfurter.dev/currencies/) from [over 100 central banks and official sources](https://frankfurter.dev/providers/). Rates update daily and go back to 1948.

## History coverage

`GET /v2/coverage` describes the default EUR-based daily blended feed. Pass the same `base`, `quotes`, and `providers`
filters as a rates query to get its coverage, for example `/v2/coverage?base=USD&quotes=ZAR&providers=BIS`.
Non-daily provider history remains available through explicit provider queries and does not enter the daily blend.

The existing `/v2/currencies?scope=all` catalogue covers eligible daily sources plus pegged currencies, while
`/v2/currencies?providers=BIS` describes that provider's recognized currencies. Those currency dates, and the dates
in `/v2/providers`, describe publication coverage. They do not establish that a requested base and quote can be
converted at the same time. Taking their minimum can advertise history that the default rates query cannot return.

For a website headline describing the default API, use **`start_date` from `/v2/coverage`**:

```javascript
const coverage = await fetch("https://api.frankfurter.dev/v2/coverage").then(r => r.json());
const headlineYear = coverage.start_date?.slice(0, 4); // Hide the history claim when null.
```

Use matching filters for pair or provider pages. Both bounds are eligible observation dates at which the selected
rates query returns at least one record; they can contain gaps. A carried quote's returned date may precede the
first date its base bridge exists. The bounds do not extend history into future days merely because carry-forward
can answer them. Multiple quotes use the rates endpoint's semantics: any matching pair suffices. No queryable pair
returns null bounds. Coverage accepts only `base`, `quotes`, and `providers`.

## Deployment

The public API runs at <https://api.frankfurter.dev>. If you prefer to host your own instance, you can run Frankfurter with Docker.

### Using Docker

The quickest way to get started:

```bash
docker run -d --init -p 8080:8080 lineofflight/frankfurter
```

For production, mount a volume to persist the SQLite database across container restarts and set any optional API keys:

```bash
docker run -d --init -p 8080:8080 \
  -e DATABASE_URL=sqlite:///app/data/frankfurter.sqlite3 \
  -e BAM_API_KEY=your_key \
  -e BANXICO_API_KEY=your_key \
  -e BCCH_USER=your_email \
  -e BCCH_PASS=your_password \
  -e BOT_API_KEY=your_key \
  -e FRED_API_KEY=your_key \
  -e TCMB_API_KEY=your_key \
  -v ./data:/app/data \
  --pull always \
  lineofflight/frankfurter
```

Without a mounted volume, the database is ephemeral and some endpoints may return empty data until their initial backfill completes.

Some data providers require API keys. All are free and optional:

- `BAM_API_KEY` — Bank Al-Maghrib (Morocco). Register at [apihelpdesk.centralbankofmorocc