frankfurter/lib/public/v1/openapi.json

{
  "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"
    }
  },
  "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": "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" }
        }
      }
    },
    "/{date}": {
      "get": {
        "tags": ["historical-rates"],
        "summary": "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" }
        }
      }
    },
    "/{start_date}..": {
      "get": {
        "tags": ["historical-rates"],
        "summary": "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" }
        }
      }
    },
    "/{start_date}..{end_date}": {
      "get": {
        "tags": ["historical-rates"],
        "summary": "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" }
        }
      }
    },
    "/currencies": {
      "get": {
        "tags": ["metadata"],
        "summary": "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" }
              }
            }
          }
        }
      }
    }
  },
  "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": 0.00001
        },
        "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"
        }
      }
    }
  }
}