335 lines
9.5 KiB
JSON
335 lines
9.5 KiB
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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|