GET /rates

GET /rates              # latest snapshot
GET /rates/YYYY-MM-DD   # historical snapshot for the given date

Response

{
  "version": "2026-05-27",
  "source": "European Commission TEDB",
  "rates": {
    "DE": {
      "country": "Germany",
      "currency": "EUR",
      "flag": "https://flagcdn.com/de.svg",
      "standard": 19,
      "reduced": [7],
      "super_reduced": null,
      "parking": null
    }
  }
}

Field meanings

• version — the situation-on date the rates apply to. This is TEDB’s own publication date, not the date you queried. For the latest endpoint, this changes once a day. For historical endpoints, it equals the path parameter.
• source — always "European Commission TEDB".
• rates[CC] — one entry per EU-27 country with a STANDARD rate on file. Countries with no current STANDARD rate are omitted, not null.
  • country — common English name.
  • currency — ISO 4217.
  • flag — URL to a flag SVG hosted on a third-party CDN. Cache it on your side if you need stability guarantees.
  • standard — single percentage value, or null if missing.
  • reduced — array of percentage values, sorted ascending. May be empty. Some countries publish multiple reduced rates (e.g. France has 5.5 and 10).
  • super_reduced — single value or null. Used by countries like Spain and Italy.
  • parking — single value or null. Used by countries like Luxembourg and Austria.

Numbers, not strings

All rate fields are JSON numbers in percentage points (not basis points, not fractions). 19 means 19%.

Cache behaviour

• Latest (/rates) — Cache-Control: public, max-age=3600, stale-while-revalidate=86400. A fresh response is at most an hour old; stale responses up to a day old may be served while we refresh.
• Historical (/rates/YYYY-MM-DD) — Cache-Control: public, max-age=31536000, immutable. Snapshots never change; cache them forever.

Errors

Status	Body	Cause
404	{"error": "no data yet"}	Latest endpoint, no cron has run on this deploy yet. Should only happen during initial setup.
404	{"error": "snapshot not found"}	Historical endpoint, no snapshot for the requested date.
401	{"error": "INVALID_KEY"}	Missing or invalid bearer token.
429	{"error": "RATE_LIMITED"} or {"error": "QUOTA_EXCEEDED"}	See rate limits.

How fresh is “latest”?

TEDB publishes once per business day. The Stawka cron polls daily at 07:00 UTC. So /rates lags TEDB by at most one day. The version field is the authoritative answer — compare it to your own clock if you need a freshness floor.