openapi: 3.0.3 info: title: Open Exchange Rates API description: >- The Open Exchange Rates API provides live and historical foreign exchange (forex) rates for 200+ world currencies as plain-text JSON over HTTPS. Endpoints cover the latest rates, end-of-day historical rates back to January 1st, 1999, bulk time-series, currency conversion, OHLC candles, and account usage. Every data request requires an App ID, passed as the app_id query parameter or an "Authorization: Token YOUR_APP_ID" header. Feature access is tiered by plan - changing the base currency requires a paid plan, time-series requires Enterprise or Unlimited, convert requires Unlimited, and OHLC requires the VIP Platinum tier. Requests to currencies.json and usage.json do not count against your monthly quota. version: '1.0' contact: name: Open Exchange Rates url: https://openexchangerates.org termsOfService: https://openexchangerates.org/terms servers: - url: https://openexchangerates.org/api description: Production security: - appIdQuery: [] - appIdHeader: [] tags: - name: Latest Rates description: Current exchange rates relative to a base currency. - name: Historical Rates description: End-of-day rates for any date back to 1999-01-01. - name: Time Series description: Bulk daily historical rates for a date range. - name: Convert description: Convert a value between two currencies at the latest rates. - name: Currencies description: List of supported currency symbols and names. - name: OHLC description: Open, high, low, close, and average rates for a period. - name: Usage description: Account plan and usage statistics. paths: /latest.json: get: operationId: getLatestRates tags: - Latest Rates summary: Get the latest exchange rates description: >- Returns the latest exchange rates available from the Open Exchange Rates API, relative to the base currency (USD by default). Rates refresh hourly on the Free and Developer plans, every 30 minutes on Enterprise, and every 5 minutes on Unlimited. parameters: - $ref: '#/components/parameters/Base' - $ref: '#/components/parameters/Symbols' - $ref: '#/components/parameters/ShowAlternative' - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: The latest exchange rates relative to the base currency. content: application/json: schema: $ref: '#/components/schemas/Rates' example: disclaimer: Usage subject to terms - https://openexchangerates.org/terms license: https://openexchangerates.org/license timestamp: 1449877801 base: USD rates: EUR: 0.913492 GBP: 0.662839 JPY: 111.7962 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessRestricted' '429': $ref: '#/components/responses/NotAllowed' /historical/{date}.json: get: operationId: getHistoricalRates tags: - Historical Rates summary: Get historical exchange rates for a date description: >- Returns the end-of-day exchange rates for a given UTC date, currently going back to January 1st, 1999. Rates are the final published values for the day through 23:59:59 UTC; requesting the current UTC date returns the most recent rates (matching latest.json). Base currency and symbols filtering are available on the Developer, Enterprise, and Unlimited plans. parameters: - name: date in: path required: true description: The requested date in YYYY-MM-DD format (UTC). schema: type: string format: date example: '2013-02-16' - $ref: '#/components/parameters/Base' - $ref: '#/components/parameters/Symbols' - $ref: '#/components/parameters/ShowAlternative' - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: End-of-day exchange rates for the requested date. content: application/json: schema: $ref: '#/components/schemas/Rates' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessRestricted' '429': $ref: '#/components/responses/NotAllowed' /time-series.json: get: operationId: getTimeSeries tags: - Time Series summary: Get bulk daily rates for a date range description: >- Returns daily historical exchange rates for a given start and end date (both inclusive). The maximum query period currently allowed is one month, and each day in the range counts as one API request against your quota. Available on the Enterprise and Unlimited plans. Use the symbols parameter to limit results and reduce payload size. parameters: - name: start in: query required: true description: The start date of the requested period (YYYY-MM-DD, inclusive). schema: type: string format: date example: '2013-01-01' - name: end in: query required: true description: The end date of the requested period (YYYY-MM-DD, inclusive). schema: type: string format: date example: '2013-01-31' - $ref: '#/components/parameters/Base' - $ref: '#/components/parameters/Symbols' - $ref: '#/components/parameters/ShowAlternative' - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: Daily exchange rates for each date in the requested range. content: application/json: schema: $ref: '#/components/schemas/TimeSeries' example: disclaimer: Usage subject to terms - https://openexchangerates.org/terms license: https://openexchangerates.org/license start_date: '2013-01-01' end_date: '2013-01-03' base: AUD rates: '2013-01-01': BTC: 0.0778595876 EUR: 0.785518 HKD: 8.04136 '2013-01-02': BTC: 0.0789399 EUR: 0.795034 HKD: 8.138096 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessRestricted' '429': $ref: '#/components/responses/NotAllowed' /convert/{value}/{from}/{to}: get: operationId: convertCurrency tags: - Convert summary: Convert a value between two currencies description: >- Converts a monetary value from one currency to another at the latest API rates, returning the original request, the exchange rate and timestamp used, and the converted amount. Available on the Unlimited plan. Validate returned values before using them anywhere transactions are processed. parameters: - name: value in: path required: true description: The value to be converted. schema: type: integer format: int32 example: 19999 - name: from in: path required: true description: The base ("from") currency as a 3-letter code. schema: type: string example: GBP - name: to in: path required: true description: The target ("to") currency as a 3-letter code. schema: type: string example: EUR - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: The conversion result with the rate and timestamp used. content: application/json: schema: $ref: '#/components/schemas/Conversion' example: disclaimer: Usage subject to terms - https://openexchangerates.org/terms license: https://openexchangerates.org/license request: query: /convert/19999/GBP/EUR amount: 19999 from: GBP to: EUR meta: timestamp: 1449885661 rate: 1.383702 response: 27673.975338 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessRestricted' '429': $ref: '#/components/responses/NotAllowed' /currencies.json: get: operationId: getCurrencies tags: - Currencies summary: Get supported currencies description: >- Returns a JSON map of all 3-letter currency codes available through the API to their full names. Requests to this endpoint do not require authentication and do not count against your account usage limit. Alternative currencies may not follow standard three-letter code formatting. security: [] parameters: - $ref: '#/components/parameters/ShowAlternative' - name: show_inactive in: query required: false description: Set to true to include historical/inactive currencies. schema: type: boolean default: false - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: A map of currency codes to full currency names. content: application/json: schema: type: object additionalProperties: type: string example: AED: United Arab Emirates Dirham EUR: Euro GBP: British Pound Sterling USD: United States Dollar VND: Vietnamese Dong /ohlc.json: get: operationId: getOhlc tags: - OHLC summary: Get OHLC rates for a period description: >- Returns open, high, low, close, and time-weighted average exchange rates for a given period. Data is available from December 19th, 2016. The start time must be an ISO-8601 UTC timestamp with zero seconds, aligned to the requested period, and the resulting end time cannot be in the future. Available to clients of the VIP Platinum tier. parameters: - name: start_time in: query required: true description: >- ISO-8601 UTC timestamp marking the start of the requested period, for example 2017-07-17T08:30:00Z. Seconds must be zero. schema: type: string format: date-time example: '2017-07-17T08:30:00Z' - name: period in: query required: true description: The requested period interval. schema: type: string enum: - 1m - 5m - 15m - 30m - 1h - 12h - 1d - 1w - 1mo - $ref: '#/components/parameters/Base' - $ref: '#/components/parameters/Symbols' - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: OHLC and average rates per currency for the period. content: application/json: schema: $ref: '#/components/schemas/Ohlc' example: disclaimer: Usage subject to terms - https://openexchangerates.org/terms license: https://openexchangerates.org/license start_time: '2017-07-17T08:30:00Z' end_time: '2017-07-17T08:35:00Z' base: USD rates: EUR: open: 0.872674 high: 0.872674 low: 0.87254 close: 0.87254 average: 0.872598 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessRestricted' '429': $ref: '#/components/responses/NotAllowed' /usage.json: get: operationId: getUsage tags: - Usage summary: Get account plan and usage statistics description: >- Returns basic plan information and usage statistics for the given App ID - account status, plan name, quota, update frequency, enabled features, requests made this month, requests remaining, days elapsed and remaining, and daily average. Requests to this endpoint do not count against your usage volume. parameters: - $ref: '#/components/parameters/PrettyPrint' responses: '200': description: Plan and usage details for the App ID. content: application/json: schema: $ref: '#/components/schemas/Usage' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: appIdQuery: type: apiKey in: query name: app_id description: Your unique App ID, passed as a query parameter. appIdHeader: type: apiKey in: header name: Authorization description: 'Your unique App ID, passed as a header: Authorization: Token YOUR_APP_ID.' parameters: Base: name: base in: query required: false description: >- Change the base currency to which all rates are relative, as a 3-letter currency code. Defaults to USD. Changing the base currency requires a paid plan. schema: type: string default: USD example: EUR Symbols: name: symbols in: query required: false description: >- Limit results to specific currencies as a comma-separated list of 3-letter currency codes. schema: type: string example: EUR,GBP,JPY ShowAlternative: name: show_alternative in: query required: false description: >- Set to true to extend returned values with alternative, black market, and digital currency rates. schema: type: boolean default: false PrettyPrint: name: prettyprint in: query required: false description: Set to true for human-readable response formatting. schema: type: boolean default: false responses: BadRequest: description: The request was invalid, such as an invalid date or parameters. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The App ID was missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true status: 401 message: invalid_app_id description: Invalid App ID provided - please sign up at https://openexchangerates.org/signup AccessRestricted: description: Access restricted, such as a feature not included in the current plan. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true status: 403 message: access_restricted description: Access restricted for the requested feature - please upgrade your plan. NotAllowed: description: The monthly usage allowance was exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Rates: type: object properties: disclaimer: type: string description: Standard usage disclaimer. license: type: string description: Link to the data license. timestamp: type: integer format: int64 description: >- UNIX time (seconds) when the rates were published. Multiply by 1000 for JavaScript milliseconds. base: type: string description: The 3-letter code of the base currency the rates are relative to. rates: type: object description: >- Exchange rates keyed by 3-letter currency code, each relative to 1 unit of the base currency. additionalProperties: type: number format: double TimeSeries: type: object properties: disclaimer: type: string license: type: string start_date: type: string format: date description: The start date of the returned series (inclusive). end_date: type: string format: date description: The end date of the returned series (inclusive). base: type: string description: The 3-letter code of the base currency. rates: type: object description: >- Daily rate objects keyed by date (YYYY-MM-DD), each mapping currency codes to rates relative to the base currency. additionalProperties: type: object additionalProperties: type: number format: double Conversion: type: object properties: disclaimer: type: string license: type: string request: type: object description: The original conversion request. properties: query: type: string amount: type: number from: type: string to: type: string meta: type: object description: The exchange rate and timestamp used for the conversion. properties: timestamp: type: integer format: int64 rate: type: number format: double response: type: number format: double description: The converted value. Ohlc: type: object properties: disclaimer: type: string license: type: string start_time: type: string format: date-time end_time: type: string format: date-time base: type: string rates: type: object description: OHLC data keyed by 3-letter currency code. additionalProperties: type: object properties: open: type: number format: double description: The exchange rate at the start of the period. high: type: number format: double description: The highest exchange rate during the period. low: type: number format: double description: The lowest exchange rate during the period. close: type: number format: double description: The exchange rate at the end of the period. average: type: number format: double description: The time-weighted mean rate for the period. Usage: type: object properties: status: type: integer example: 200 data: type: object properties: app_id: type: string description: The App ID the statistics relate to. status: type: string description: Account status, such as active or access_restricted. plan: type: object properties: name: type: string description: The current subscription tier. quota: type: string description: Monthly request allowance in display format. update_frequency: type: string description: How often rates refresh on this plan. features: type: object description: Feature flags enabled on this plan. properties: base: type: boolean symbols: type: boolean experimental: type: boolean time-series: type: boolean convert: type: boolean usage: type: object properties: requests: type: integer description: Requests made in the current month. requests_quota: type: integer description: The monthly request limit. requests_remaining: type: integer description: Requests remaining this month. days_elapsed: type: integer description: Days since the current billing month began. days_remaining: type: integer description: Days until the next billing cycle. daily_average: type: integer description: Average daily request volume this month. Error: type: object properties: error: type: boolean status: type: integer description: The HTTP status code. message: type: string description: A machine-readable error code such as invalid_app_id or access_restricted. description: type: string description: A human-readable explanation of the error.