Frankfurter - Convert Currency at Today's ECB Euro Reference Rate (official API, ECB provider route)

import json, time
from datetime import date, datetime, timedelta
from zoneinfo import ZoneInfo
 
AMOUNT, CCY = 250, "USD"  # convert AMOUNT CCY -> EUR at the ECB euro reference rate
 
SITE = "https://api.frankfurter.dev"
ECB = SITE + "/v2/providers/ecb"  # ECB provider route only; the blended /v2/rate and /v2/rates mix in other providers
ECB_PAGE = "https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html"
PAUSE = 1.0  # Frankfurter: no quotas, "rate-limited to prevent abuse"; keep calls serial
 
def on_api_tab():
    """fetch() runs same-origin from a logged-out api.frankfurter.dev tab (the ECB provider record, plain JSON). Reuse it."""
    try:
        if js("location.origin") == SITE:
            return
    except Exception:
        pass
    new_tab(ECB)
    wait_for_load()
    body = js("document.body ? document.body.innerText : ''") or ""
    if js("location.origin") != SITE or '"key":"ECB"' not in body.replace(" ", ""):
        raise RuntimeError(f"api.frankfurter.dev did not serve the ECB provider record (at {js('location.href')}): stop")
 
# js() gives up after a few seconds, so start the fetch, then poll for it.
START_JS = """(() => { window.__fx = window.__fx || {}; const id = String(Math.random()).slice(2); window.__fx[id] = null;
  fetch(%s, {credentials: 'omit'})
    .then(async r => { window.__fx[id] = {status: r.status, type: r.headers.get('content-type'), text: await r.text()}; })
    .catch(e => { window.__fx[id] = {status: 0, type: '', text: String(e)}; });
  return id; })()"""
POLL_JS = """(() => { const v = window.__fx[%s]; if (v) delete window.__fx[%s]; return v; })()"""
 
def get(url, timeout=30):
    """GET url from inside the tab -> parsed JSON. Errors are JSON {"status":422,"message":"invalid currency: ABC"}.
    Waits 30 s once on 429/5xx, raises on anything else, so an error never looks like a rate."""
    for attempt in range(2):
        rid = json.dumps(js(START_JS % json.dumps(url)))
        t0 = time.time()
        while (r := js(POLL_JS % (rid, rid))) is None:
            if time.time() - t0 > timeout:
                raise RuntimeError(f"{url}: no answer after {timeout}s")
            time.sleep(0.3)
        time.sleep(PAUSE)
        if r["status"] == 200 and "json" in (r["type"] or ""):
            return json.loads(r["text"])
        if r["status"] in (0, 429, 500, 502, 503, 504) and attempt == 0:
            time.sleep(30)
            continue
        raise RuntimeError(f"{url}: HTTP {r['status']} {' '.join(r['text'].split())[:160]!r}; stopping")
 
def latest_expected(now):
    """The ECB publishes 'at around 16:00 CET every working day, except on TARGET closing days'. Most recent weekday
    whose fixing should be out by now (TARGET holidays not modelled: a mismatch is a warning, not an error)."""
    d = now.date() if now.hour * 60 + now.minute >= 16 * 60 + 30 else now.date() - timedelta(days=1)
    while d.weekday() >= 5:
        d -= timedelta(days=1)
    return d
 
on_api_tab()
prov = get(ECB)
if prov["key"] != "ECB" or prov["pivot_currency"] != "EUR":
    raise RuntimeError(f"unexpected provider record: {prov['key']} pivot {prov['pivot_currency']}")
if CCY not in prov["currencies"]:
    raise RuntimeError(f"the ECB does not publish {CCY}; this skill cannot answer for it")
print(f"provider: {prov['name']} ({prov['rate_type']}, pivot {prov['pivot_currency']}), data {prov['start_date']} .. {prov['end_date']}")
print(f"  source: {prov['data_url']}\n  terms:  {prov['terms_url']}")
 
# The ECB publishes EUR-based rates (EUR 1 = x CCY). That is the official figure; the other direction is an inversion.
pub = get(f"{ECB}/rate/EUR/{CCY}")
inv = get(f"{ECB}/rate/{CCY}/EUR")  # Frankfurter's inversion of it, rounded (0.89871)
for d, b, q in ((pub, "EUR", CCY), (inv, CCY, "EUR")):
    if (d["base"], d["quote"]) != (b, q):
        raise RuntimeError(f"asked {b}/{q}, got {d['base']}/{d['quote']}")
if pub["date"] != inv["date"]:
    raise RuntimeError(f"dates disagree: EUR pair {pub['date']}, inverted {inv['date']}")
if pub["date"] != prov["end_date"]:  # a separately cached response (cache-control max-age), can lag a new fixing
    print(f"  note: provider record ends {prov['end_date']}, rate is dated {pub['date']}; quoting the rate's date")
 
now = datetime.now(ZoneInfo("Europe/Berlin"))  # CET/CEST, the ECB's clock
want = latest_expected(now)
got = date.fromisoformat(pub["date"])
print(f"\nnow in Frankfurt {now:%Y-%m-%d %H:%M %Z}; latest expected fixing {want}; API fixing date {got}")
if got > now.date() or (now.date() - got).days > 7:
    raise RuntimeError(f"fixing date {got} is impossible or stale; stop")
if got != want:
    print(f"  WARNING: expected {want}; a TARGET closing day or a late publication. Quote the date you got.")
 
official = pub["rate"]  # EUR 1 = official CCY
amount = AMOUNT / official
check = AMOUNT * inv["rate"]
if abs(official * inv["rate"] - 1) > 1e-4:  # the inverted rate is rounded to 5 significant digits
    raise RuntimeError(f"inversion disagrees: {official} x {inv['rate']} = {official * inv['rate']:.6f}, not 1")
print(f"ECB EUR/{pub['quote']} {official} on {pub['date']}; Frankfurter {inv['base']}/{inv['quote']} {inv['rate']}")
print(f"  {AMOUNT} {CCY} / {official} = {amount:.4f} -> {amount:,.2f} EUR   (via the inverted rate: {check:.4f})")
 
# Cross-check against the ECB's own page (one page load; robots.txt has only a * group, Crawl-delay 5).
goto_url(ECB_PAGE)  # same tab; a later on_api_tab() sees the ECB origin and opens a fresh API tab
wait_for_load()
row = js("""(() => { const td = document.querySelector('td#%s'); const tr = td && td.closest('tr');
  const h = document.querySelector('.jumbo-box h3');
  return {rate: tr && tr.querySelector('.rate') && tr.querySelector('.rate').textContent.trim(), day: h && h.textContent.trim()}; })()"""
         % CCY)
if not row or not row["rate"] or not row["day"]:
    raise RuntimeError(f"ECB page layout changed (got {row!r}); use the API figure and say it was not cross-checked")
ecb_day = datetime.strptime(row["day"], "%d %B %Y").date()
print(f"\nECB page ({row['day']}): EUR 1 = {row['rate']} {CCY}")
if float(row["rate"]) != official or ecb_day != got:
    raise RuntimeError(f"ECB page says {row['rate']} on {ecb_day}, API says {official} on {got}: stop")
print("  matches the API")
 
print(f"\nanswer: {AMOUNT} {CCY} = {amount:,.2f} EUR at the ECB euro reference rate of {pub['date']} (EUR 1 = {official} {CCY}).")
print("  Source: European Central Bank, euro foreign exchange reference rates (" + ECB_PAGE + "), via Frankfurter;")
print(f"  the {CCY}->EUR figure is calculated from the ECB's EUR/{CCY} rate ({AMOUNT} / {official}); the ECB publishes only EUR/{CCY}.")

provider: European Central Bank (reference rate, pivot EUR), data 1999-01-04 .. 2026-11-11
  source: https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html
  terms:  https://www.ecb.europa.eu/services/using-our-site/disclaimer/html/index.en.html
 
now in Frankfurt 2026-11-12 00:24 CET; latest expected fixing 2026-11-11; API fixing date 2026-11-11
ECB EUR/USD 1.1127 on 2026-11-11; Frankfurter USD/EUR 0.89871
  250 USD / 1.1127 = 224.6787 -> 224.68 EUR   (via the inverted rate: 224.6775)
 
ECB page (11 November 2026): EUR 1 = 1.1127 USD
  matches the API
 
answer: 250 USD = 224.68 EUR at the ECB euro reference rate of 2026-11-11 (EUR 1 = 1.1127 USD).
  Source: European Central Bank, euro foreign exchange reference rates (https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html), via Frankfurter;
  the USD->EUR figure is calculated from the ECB's EUR/USD rate (250 / 1.1127); the ECB publishes only EUR/USD.

import json, time
 
SITE = "https://api.frankfurter.dev"
ECB = SITE + "/v2/providers/ecb"
DOCS = "https://frankfurter.dev/"
 
# The docs FAQ, as the page shows it: commercial use, provider terms, rate limits.
new_tab(DOCS)
wait_for_load()
text = " ".join((js("document.body.innerText") or "").split())
if "Frankfurter" not in text:
    raise RuntimeError(f"frankfurter.dev did not serve its docs (at {js('location.href')}): stop")
for q in ("Is the API free for commercial use?", "Does the API have any call limits?", "There's no conversion endpoint"):
    i = text.find(q)
    if i < 0:
        raise RuntimeError(f"docs FAQ changed, {q!r} not found: re-read https://frankfurter.dev/ before relying on this skill")
    cut = text[i:i + 260]
    print("docs:", cut[:cut.rfind(". ") + 1] + "\n")
 
# Same-origin probes from an api.frankfurter.dev page, same tab. No retries: this block only inspects answers.
goto_url(ECB)
wait_for_load()
if js("location.origin") != SITE:
    raise RuntimeError(f"not on {SITE} (at {js('location.href')}): stop")
 
START_JS = """(() => { window.__fx = window.__fx || {}; const id = String(Math.random()).slice(2); window.__fx[id] = null;
  fetch(%s, {credentials: 'omit'})
    .then(async r => { window.__fx[id] = {status: r.status, type: r.headers.get('content-type'), text: await r.text()}; })
    .catch(e => { window.__fx[id] = {status: 0, type: '', text: String(e)}; });
  return id; })()"""
POLL_JS = """(() => { const v = window.__fx[%s]; if (v) delete window.__fx[%s]; return v; })()"""
 
def raw(url, timeout=30):
    rid = json.dumps(js(START_JS % json.dumps(url)))
    t0 = time.time()
    while (r := js(POLL_JS % (rid, rid))) is None:
        if time.time() - t0 > timeout:
            raise RuntimeError(f"{url}: no answer after {timeout}s")
        time.sleep(0.3)
    time.sleep(1.0)
    return r["status"], r["type"], " ".join(r["text"].split())
 
s, t, body = raw(SITE + "/robots.txt")
print(f"api robots.txt: HTTP {s} {t} {body!r}\n")
for path in ("/rate/usd/eur",                 # lower case is fine
             "/rate/USD/EUR?date=2026-11-08",  # Sunday -> previous fixing
             "/rate/USD/EUR?date=2026-11-20",  # future -> latest fixing, no error
             "/rate/EUR/NGN",                  # a currency the ECB does not publish
             "/rate/EUR/ABC",                  # not a currency
             "/rate/USD/EUR?date=2026-13-01",  # bad date
             "/rate/USD/EUR?date=1998-12-31"): # before the euro
    s, t, body = raw(ECB + path)
    print(f"{path}: HTTP {s} {t} {body[:100]}")

docs: Is the API free for commercial use? Yes. Blended rates are Frankfurter's own calculation and free to use. Direct queries to individual provider endpoints remain subject to each provider's terms. Can I store or cache rates in my own database? Yes.
 
docs: Does the API have any call limits? There are no quotas. Requests are rate-limited to prevent abuse, but there are no monthly or daily caps. For high-volume use, consider caching responses, self-hosting, or querying the datasets directly.
 
docs: There's no conversion endpoint. Fetch the rate and convert in a few lines of code.
 
api robots.txt: HTTP 200 text/plain 'User-agent: * Allow: /'
 
/rate/usd/eur: HTTP 200 application/json; charset=utf-8 {"date":"2026-11-11","base":"USD","quote":"EUR","rate":0.89871}
/rate/USD/EUR?date=2026-11-08: HTTP 200 application/json; charset=utf-8 {"date":"2026-11-06","base":"USD","quote":"EUR","rate":0.89566}
/rate/USD/EUR?date=2026-11-20: HTTP 200 application/json; charset=utf-8 {"date":"2026-11-11","base":"USD","quote":"EUR","rate":0.89871}
/rate/EUR/NGN: HTTP 404 application/json; charset=utf-8 {"status":404,"message":"not found"}
/rate/EUR/ABC: HTTP 422 application/json; charset=utf-8 {"status":422,"message":"invalid currency: ABC"}
/rate/USD/EUR?date=2026-13-01: HTTP 422 application/json; charset=utf-8 {"status":422,"message":"invalid date"}
/rate/USD/EUR?date=1998-12-31: HTTP 404 application/json; charset=utf-8 {"status":404,"message":"not found"}

import json, sys, time, urllib.error, urllib.request
import xml.etree.ElementTree as ET
 
AMOUNT, CCY = 250, "USD"  # convert AMOUNT CCY -> EUR
ECB = "https://api.frankfurter.dev/v2/providers/ecb"
ECB_XML = "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml"  # linked from the ECB reference-rates page
 
def get(url):
    """GET -> (status, body). Python's default User-Agent got HTTP 200 from both hosts."""
    try:
        with urllib.request.urlopen(url, timeout=30) as r:
            return r.status, r.read().decode()
    except urllib.error.HTTPError as e:
        return e.code, e.read().decode()
 
s, body = get(f"{ECB}/rate/EUR/{CCY}")
if s != 200:
    sys.exit(f"Frankfurter: HTTP {s} {body[:120]}")  # e.g. 404 {"status":404,"message":"not found"} for a non-ECB currency
fx = json.loads(body)
if (fx["base"], fx["quote"]) != ("EUR", CCY):
    sys.exit(f"asked EUR/{CCY}, got {fx['base']}/{fx['quote']}")
print(f"Frankfurter ECB route: {fx['date']} EUR 1 = {fx['rate']} {CCY}")
 
time.sleep(5)  # www.ecb.europa.eu robots.txt: Crawl-delay: 5
s, body = get(ECB_XML)
if s != 200:
    sys.exit(f"ECB XML: HTTP {s}")
ns = {"e": "http://www.ecb.int/vocabulary/2002-08-01/eurofxref"}
day = ET.fromstring(body).find(".//e:Cube[@time]", ns)
row = day.find(f"e:Cube[@currency='{CCY}']", ns)
if row is None:
    sys.exit(f"the ECB XML has no {CCY} row for {day.get('time')}")
print(f"ECB eurofxref-daily.xml: {day.get('time')} EUR 1 = {row.get('rate')} {CCY}")
if (day.get("time"), float(row.get("rate"))) != (fx["date"], fx["rate"]):
    sys.exit("Frankfurter and the ECB disagree: quote the ECB figure and date")
 
print(f"{AMOUNT} {CCY} = {AMOUNT / fx['rate']:,.2f} EUR (ECB reference rate {fx['date']}, calculated as {AMOUNT} / {fx['rate']})")

Frankfurter ECB route: 2026-11-11 EUR 1 = 1.1127 USD
ECB eurofxref-daily.xml: 2026-11-11 EUR 1 = 1.1127 USD
250 USD = 224.68 EUR (ECB reference rate 2026-11-11, calculated as 250 / 1.1127)

B=https://api.frankfurter.dev/v2/providers/ecb   # ECB route; not /v2/rate (blended)
curl -sS --fail "$B/rate/EUR/USD" | python3 -c '
import json, sys
d = json.load(sys.stdin)
eur = 250 / d["rate"]
print(d["date"], "EUR 1 =", d["rate"], "USD -> 250 USD =", "%.2f" % eur, "EUR")
'
sleep 1
curl -sS --fail "$B/rates?base=USD&quotes=EUR,GBP"; echo   # several quotes in one call (inverted from EUR)
sleep 1
curl -sS -o /dev/null -w 'not an ECB currency (EUR/NGN): HTTP %{http_code} %{content_type}\n' "$B/rate/EUR/NGN"

2026-11-11 EUR 1 = 1.1127 USD -> 250 USD = 224.68 EUR
[{"date":"2026-11-11","base":"USD","quote":"EUR","rate":0.89871},{"date":"2026-11-11","base":"USD","quote":"GBP","rate":0.75149}]
not an ECB currency (EUR/NGN): HTTP 404 application/json; charset=utf-8