openapi: 3.1.2
info:
  title: Frankfurter Currencies Rates API
  description: Frankfurter is an open-source API for current and historical foreign exchange rates, sourcing currency data from public providers like the European Central Bank.
  version: 1.0.0
  license:
    name: MIT
    url: https://github.com/lineofflight/frankfurter/blob/main/LICENSE
  contact:
    url: https://github.com/lineofflight/frankfurter/issues
  x-generated-from: upstream
  x-last-validated: '2026-05-29'
servers:
- url: https://api.frankfurter.dev/v1
tags:
- name: Rates
  description: Blended currency exchange rates
paths:
  /rates:
    get:
      operationId: getRates
      summary: Frankfurter Get Exchange Rates
      description: Returns exchange rates blended across providers. Without date params, returns the latest rates. Each record is a single currency pair.
      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: USD
                rate: 1.089
              - date: '2024-01-15'
                base: EUR
                quote: GBP
                rate: 0.8623
            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'
      tags:
      - Rates
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /rate/{base}/{quote}:
    get:
      operationId: getRate
      summary: Frankfurter Get a Single Exchange Rate Pair
      description: Returns the blended exchange rate for a single currency pair. Without a date param, returns the latest rate.
      parameters:
      - name: base
        in: path
        required: true
        schema:
          type: string
          example: EUR
      - name: quote
        in: path
        required: true
        schema:
          type: string
          example: USD
      - $ref: '#/components/parameters/date'
      - $ref: '#/components/parameters/providers'
      responses:
        '200':
          description: Exchange rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rate'
              example:
                date: '2026-03-25'
                base: EUR
                quote: USD
                rate: 1.1568
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Rates
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Rate:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date of the rate
        base:
          type: string
          description: Base currency code
        quote:
          type: string
          description: Quote currency 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 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. Omitted on synthesized peg rows where no provider published the quote.'
          items:
            type: object
            properties:
              key:
                type: string
                description: Provider key
              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
            - rate
      required:
      - date
      - base
      - quote
      - rate
  parameters:
    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, rate }` objects per record showing each provider''s individual 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
    quotes:
      name: quotes
      in: query
      description: Comma-separated list of quote currencies to include
      required: false
      schema:
        type: string
        example: USD,GBP,JPY
    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
    from:
      name: from
      in: query
      description: Start of date range (YYYY-MM-DD)
      required: false
      schema:
        type: string
        format: date
        example: '2024-01-01'
    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'
    base:
      name: base
      in: query
      description: 'Base currency (default: EUR)'
      required: false
      schema:
        type: string
        default: EUR
        example: USD
    providers:
      name: providers
      in: query
      description: Comma-separated list of data providers to include
      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'
  responses:
    NotFound:
      description: No data found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    UnprocessableEntity:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string