openapi: 3.1.2
info:
  title: Frankfurter 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: current-rates
    description: Latest foreign exchange rates
  - name: historical-rates
    description: Historical exchange rates for specific dates and periods
  - name: metadata
    description: API reference data like available currencies
paths:
  /latest:
    get:
      tags:
        - current-rates
      summary: Frankfurter Get the Latest Rates
      description: Returns the last working day's rates
      parameters:
        - $ref: '#/components/parameters/base'
        - $ref: '#/components/parameters/symbols'
      responses:
        '200':
          description: Latest rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratesOnDate'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{date}:
    get:
      tags:
        - historical-rates
      summary: Frankfurter Get Rates for a Past Date
      description: Returns historical rates for the working day closest to the specified date
      parameters:
        - name: date
          in: path
          description: The date for the historical rates
          required: true
          schema:
            $ref: '#/components/schemas/date'
        - $ref: '#/components/parameters/base'
        - $ref: '#/components/parameters/symbols'
      responses:
        '200':
          description: Historical rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratesOnDate'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{start_date}..:
    get:
      tags:
        - historical-rates
      summary: Frankfurter Get Rates for a Time Period
      description: Returns historical rates for every day within a time period starting from the provided date until today.
      parameters:
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/base'
        - $ref: '#/components/parameters/symbols'
      responses:
        '200':
          $ref: '#/components/responses/PeriodRateGetResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{start_date}..{end_date}:
    get:
      tags:
        - historical-rates
      summary: Frankfurter Get Rates for a Time Period
      description: Returns historical rates for every day within a time period. The end date defaults to today if not provided.
      parameters:
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/base'
        - $ref: '#/components/parameters/symbols'
      responses:
        '200':
          $ref: '#/components/responses/PeriodRateGetResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /currencies:
    get:
      tags:
        - metadata
      summary: Frankfurter Get Available Currencies
      description: Returns a list of available currencies with their full names
      responses:
        '200':
          description: List of available currencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/currencies'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    base:
      name: base
      in: query
      description: Base currency to convert from
      required: false
      schema:
        $ref: '#/components/schemas/baseIn'
    symbols:
      name: symbols
      in: query
      description: Comma-separated list of currencies to convert to
      required: false
      schema:
        type: array
        description: A list of currencies
        items:
          $ref: '#/components/schemas/base'
        minItems: 1
      explode: false
      example: USD,GBP
    start_date:
      name: start_date
      in: path
      required: true
      description: The start date for the period
      schema:
        $ref: '#/components/schemas/date'
    end_date:
      name: end_date
      in: path
      required: true
      description: The end date for the period
      schema:
        $ref: '#/components/schemas/date'
  responses:
    PeriodRateGetResponse:
      description: Historical rates for the period
      content:
        application/json:
          schema:
            title: RatesDuringPeriod
            type: object
            properties:
              amount:
                $ref: '#/components/schemas/amount'
              base:
                $ref: '#/components/schemas/base'
              start_date:
                $ref: '#/components/schemas/date'
              end_date:
                $ref: '#/components/schemas/date'
              rates:
                $ref: '#/components/schemas/ratesByDate'
            required:
              - base
              - start_date
              - end_date
              - rates
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: not found
  schemas:
    amount:
      type: number
      description: The amount to convert
      exclusiveMinimum: 0
    date:
      type: string
      format: date
      example: '2024-01-15'
      description: Date in YYYY-MM-DD format, all dates stored in UTC.
    base:
      type: string
      enum:
        - AUD
        - BGN
        - BRL
        - CAD
        - CHF
        - CNY
        - CZK
        - DKK
        - EUR
        - GBP
        - HKD
        - HUF
        - IDR
        - ILS
        - INR
        - ISK
        - JPY
        - KRW
        - MXN
        - MYR
        - NOK
        - NZD
        - PHP
        - PLN
        - RON
        - SEK
        - SGD
        - THB
        - TRY
        - USD
        - ZAR
      description: The base currency code following ISO4217
    baseIn:
      allOf:
        - $ref: '#/components/schemas/base'
      default: EUR
    rates:
      type: object
      description: Exchange rates keyed by currency code
      propertyNames:
        $ref: '#/components/schemas/base'
      additionalProperties:
        type: number
        exclusiveMinimum: 0
        multipleOf: 1e-05
      minProperties: 1
      example:
        AUD: 1.91
        CAD: 1.8004
        CHF: 1.6168
        CYP: 0.58231
    ratesOnDate:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/amount'
        base:
          $ref: '#/components/schemas/base'
        date:
          $ref: '#/components/schemas/date'
        rates:
          $ref: '#/components/schemas/rates'
      required:
        - base
        - date
        - rates
    ratesByDate:
      type: object
      description: Mapping of date → rates object
      propertyNames:
        $ref: '#/components/schemas/date'
      additionalProperties:
        $ref: '#/components/schemas/rates'
      minProperties: 1
      example:
        '1999-01-04':
          AUD: 1.91
        '1999-01-05':
          AUD: 1.8944
        '1999-01-06':
          AUD: 1.882
    currencies:
      type: object
      propertyNames:
        $ref: '#/components/schemas/base'
      additionalProperties:
        type: string
        description: Full name of the currency
        minLength: 1
      minProperties: 1
      example:
        AUD: Australian Dollar
        BGN: Bulgarian Lev
        EUR: Euro
        USD: US Dollar