Open Exchange Rates Convert API

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.