openapi: 3.0.3
info:
  title: Open Exchange Rates Convert 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: Convert
  description: Convert a value between two currencies at the latest rates.
paths:
  /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'
components:
  responses:
    NotAllowed:
      description: The monthly usage allowance was exceeded.
      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.
  schemas:
    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.
    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.
  parameters:
    PrettyPrint:
      name: prettyprint
      in: query
      required: false
      description: Set to true for human-readable response formatting.
      schema:
        type: boolean
        default: false
  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.'