Frankfurter Rates API

openapi: 3.2.0
info:
  title: Frankfurter Rates API
  description: Frankfurter is an open-source API for current and historical foreign exchange rates published by central banks.
  version: 2.1.1
  license:
    name: MIT
    url: https://github.com/lineofflight/frankfurter/blob/main/LICENSE
  contact:
    url: https://github.com/lineofflight/frankfurter/issues
servers:
- url: https://api.frankfurter.dev/v2
tags:
- name: Rates
paths:
  /rates:
    get:
      operationId: getRates
      summary: Get exchange rates
      description: 'Returns exchange rates blended across providers. Without date params, returns the latest rates. Each record is a single currency pair. The response includes an identity record for the base currency (base equals quote, rate 1), subject to the quotes filter like any other record. Daily date ranges of any length are served, including full history. Limit: requests using `providers` or `expand=providers` recompute the blend per date, so at daily granularity they return 422 for ranges longer than 5 years. A single provider is exempt and serves any range. With `providers` naming 2 to 5 providers, a `quotes` list of at most 5 currencies lifts the cap; without `providers`, `expand=providers` ranges compute every currency regardless of `quotes`, so aggregate with `group=week` or `group=month`, add `providers`, or split the range into shorter requests.'
      parameters:
      - $ref: '#/components/parameters/date'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/base'
      - $ref: '#/components/parameters/quotes'
      - $ref: '#/components/parameters/providers'
      - $ref: '#/components/parameters/group'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: Exchange rates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rate'
              example:
              - date: '2024-01-15'
                base: EUR
                quote: EUR
                rate: 1.0
              - date: '2024-01-15'
                base: EUR
                quote: GBP
                rate: 0.8623
              - date: '2024-01-15'
                base: EUR
                quote: USD
                rate: 1.089
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON stream of Rate objects, one JSON object per line
              example: '{ "date": "2024-01-15", "base": "EUR", "quote": "USD", "rate": 1.089 }

                { "date": "2024-01-15", "base": "EUR", "quote": "GBP", "rate": 0.8623 }

                '
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      tags:
      - Rates
components:
  parameters:
    group:
      name: group
      in: query
      description: Downsample rates by time period. Only applies to date ranges.
      required: false
      schema:
        type: string
        enum:
        - week
        - month
        example: month
    base:
      name: base
      in: query
      description: 'Base currency (default: EUR)'
      required: false
      schema:
        type: string
        default: EUR
        example: USD
    from:
      name: from
      in: query
      description: Start of date range (YYYY-MM-DD)
      required: false
      schema:
        type: string
        format: date
        example: '2024-01-01'
    quotes:
      name: quotes
      in: query
      description: Comma-separated list of quote currencies to include
      required: false
      schema:
        type: string
        example: USD,GBP,JPY
    date:
      name: date
      in: query
      description: Specific date (YYYY-MM-DD). Cannot be combined with from/to.
      required: false
      schema:
        type: string
        format: date
        example: '2024-01-15'
    providers:
      name: providers
      in: query
      description: Comma-separated list of data providers to include. A single provider includes its stored non-currency series. Selecting multiple providers blends only registered currencies and accounting units.
      required: false
      schema:
        type: string
        example: ECB,TCMB
    to:
      name: to
      in: query
      description: End of date range (YYYY-MM-DD). Defaults to today.
      required: false
      schema:
        type: string
        format: date
        example: '2024-01-31'
    expand:
      name: expand
      in: query
      description: 'Comma-separated list of optional fields to include per record. Currently supports `providers`, which adds an array of `{ key, date, rate }` objects per record showing each provider''s individual observation date and rate. Outliers excluded from the blend (and providers whose rate was overridden by a currency peg) are flagged with `excluded: true`. The field is omitted on synthesized peg rows where no provider published the quote. In CSV output, the `providers` column is encoded as `KEY:RATE` pairs joined by `|`, with a trailing `*` on excluded entries (e.g. `ECB:0.92|FED:1.50*`).'
      required: false
      schema:
        type: string
        enum:
        - providers
        example: providers
  responses:
    ServiceUnavailable:
      description: 'The request deadline expired before the response could be computed, or the worker process is already running its limit of concurrent live daily-range computes (any daily range served live: with providers, with expand=providers, or before the precomputed blend is ready). In the second case a Retry-After header says how many seconds to wait before retrying. Otherwise retry with a narrower request: filter with quotes, aggregate with group, or split the range into shorter requests.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying. Sent when the server is at its limit of concurrent daily range computes.
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    UnprocessableEntity:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    NotFound:
      description: No data found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  schemas:
    Rate:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date of the rate
        base:
          type: string
          description: Base currency or accounting unit code
        quote:
          type: string
          description: Quote currency or accounting unit code
        rate:
          type: number
          description: Exchange rate value
          exclusiveMinimum: 0
        providers:
          type: array
          description: 'Per-provider rates for this pair. Present only when `expand=providers` is set. Each entry has the provider''s observation date and published rate (rebased to the row''s base). Entries with `excluded: true` did not contribute to the blended `rate` — either flagged as outliers by the consensus filter, or overridden by a currency peg. A one-day typo in a provider''s series is left out, so its entry shows the observation before it. Omitted on synthesized peg rows where no provider published the quote.'
          items:
            type: object
            properties:
              key:
                type: string
                description: Provider key
              date:
                type: string
                format: date
                description: Provider observation date used for this entry
              rate:
                type: number
                exclusiveMinimum: 0
                description: Provider's rate, rebased to the row's base
              excluded:
                type: boolean
                description: Present and true when this entry did not contribute to the blended rate
            required:
            - key
            - date
            - rate
      required:
      - date
      - base
      - quote
      - rate