ExchangeRate-API Exchange Rates API

openapi: 3.0.3
info:
  title: ExchangeRate Account Exchange Rates API
  description: 'ExchangeRate-API provides real-time and historical currency exchange rates for 165 currencies across 200 countries. Operating since 2010, the service delivers reliable currency conversion data via simple HTTP GET requests. Authentication is supported via API key embedded in the URL path or via Bearer token header. A free tier is available with 1,500 monthly requests and daily updates; paid plans offer hourly or 5-minute update frequencies and higher quotas. Historical data is available back to 1990.

    '
  version: '6'
  termsOfService: https://www.exchangerate-api.com/terms
  contact:
    name: ExchangeRate-API Support
    email: support@exchangerate-api.com
  x-api-id: exchangerate:exchangerate-api
  x-provider-name: ExchangeRate-API
servers:
- url: https://v6.exchangerate-api.com/v6
  description: ExchangeRate-API v6 endpoint (API key in URL path)
- url: https://v6.exchangerate-api.com/v6
  description: ExchangeRate-API v6 endpoint (Bearer token auth — omit key from path)
security:
- BearerAuth: []
tags:
- name: Exchange Rates
  description: Real-time and historical currency exchange rate endpoints
paths:
  /{apiKey}/latest/{baseCurrency}:
    get:
      operationId: getLatestRates
      summary: Get latest exchange rates
      description: 'Returns the latest exchange rates for all supported currencies relative to the supplied base currency. Available on all plans including the free tier.

        '
      tags:
      - Exchange Rates
      security:
      - {}
      parameters:
      - $ref: '#/components/parameters/apiKey'
      - $ref: '#/components/parameters/baseCurrency'
      responses:
        '200':
          description: Successful response with latest exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: Fri, 27 Mar 2020 00:00:00 +0000
                time_next_update_unix: 1585353600
                time_next_update_utc: Sat, 28 Mar 2020 00:00:00 +0000
                base_code: USD
                conversion_rates:
                  USD: 1
                  EUR: 0.8876
                  GBP: 0.7901
                  JPY: 107.53
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authentication error (invalid key, inactive account, quota reached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /latest/{baseCurrency}:
    get:
      operationId: getLatestRatesBearer
      summary: Get latest exchange rates (Bearer token auth)
      description: 'Returns the latest exchange rates for all supported currencies relative to the supplied base currency. Uses Bearer token authentication via the Authorization header rather than an API key in the URL path.

        '
      tags:
      - Exchange Rates
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/baseCurrency'
      responses:
        '200':
          description: Successful response with latest exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/pair/{baseCurrency}/{targetCurrency}:
    get:
      operationId: getPairRate
      summary: Get conversion rate for a currency pair
      description: 'Returns the conversion rate between two specific currencies. Provides a minimal JSON response focused on the pair relationship. Available on all plans.

        '
      tags:
      - Exchange Rates
      security:
      - {}
      parameters:
      - $ref: '#/components/parameters/apiKey'
      - $ref: '#/components/parameters/baseCurrency'
      - $ref: '#/components/parameters/targetCurrency'
      responses:
        '200':
          description: Successful pair conversion rate response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairRateResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: Fri, 27 Mar 2020 00:00:00 +0000
                time_next_update_unix: 1585353600
                time_next_update_utc: Sat, 28 Mar 2020 00:00:00 +0000
                base_code: EUR
                target_code: GBP
                conversion_rate: 0.8412
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/pair/{baseCurrency}/{targetCurrency}/{amount}:
    get:
      operationId: getPairConversion
      summary: Convert an amount between a currency pair
      description: 'Returns the conversion rate between two currencies and the result of converting the specified amount. Available on all plans.

        '
      tags:
      - Exchange Rates
      security:
      - {}
      parameters:
      - $ref: '#/components/parameters/apiKey'
      - $ref: '#/components/parameters/baseCurrency'
      - $ref: '#/components/parameters/targetCurrency'
      - name: amount
        in: path
        required: true
        description: The amount to convert (decimal format, e.g. 1234.5678)
        schema:
          type: number
          format: double
          example: 7
      responses:
        '200':
          description: Successful pair conversion response with conversion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairConversionResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: Fri, 27 Mar 2020 00:00:00 +0000
                time_next_update_unix: 1585353600
                time_next_update_utc: Sat, 28 Mar 2020 00:00:00 +0000
                base_code: EUR
                target_code: GBP
                conversion_rate: 0.8412
                conversion_result: 5.8884
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/history/{baseCurrency}/{year}/{month}/{day}:
    get:
      operationId: getHistoricalRates
      summary: Get historical exchange rates for a specific date
      description: 'Returns exchange rates for all supported currencies on a specific historical date. Historical data is available back to 1990. Requires a paid subscription plan.

        '
      tags:
      - Exchange Rates
      security:
      - {}
      parameters:
      - $ref: '#/components/parameters/apiKey'
      - $ref: '#/components/parameters/baseCurrency'
      - name: year
        in: path
        required: true
        description: Four-digit year (e.g. 2023)
        schema:
          type: integer
          minimum: 1990
          example: 2023
      - name: month
        in: path
        required: true
        description: Month number (1-12)
        schema:
          type: integer
          minimum: 1
          maximum: 12
          example: 3
      - name: day
        in: path
        required: true
        description: Day of month (1-31)
        schema:
          type: integer
          minimum: 1
          maximum: 31
          example: 15
      responses:
        '200':
          description: Successful response with historical exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                base_code: USD
                year: 2023
                month: 3
                day: 15
                requested_time: '2023-03-15T00:00:01+00:00'
                conversion_rates:
                  USD: 1
                  EUR: 0.9343
                  GBP: 0.8192
        '403':
          description: Authentication error or plan restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code or date out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    apiKey:
      name: apiKey
      in: path
      required: true
      description: Your personal API key obtained from the ExchangeRate-API dashboard
      schema:
        type: string
        example: YOUR-API-KEY
    baseCurrency:
      name: baseCurrency
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the base currency (e.g. USD, EUR, GBP)
      schema:
        type: string
        minLength: 3
        maxLength: 3
        pattern: ^[A-Z]{3}$
        example: USD
    targetCurrency:
      name: targetCurrency
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the target currency (e.g. GBP, JPY)
      schema:
        type: string
        minLength: 3
        maxLength: 3
        pattern: ^[A-Z]{3}$
        example: GBP
  schemas:
    LatestRatesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseMetadata'
      - $ref: '#/components/schemas/TimestampFields'
      - type: object
        required:
        - result
        - base_code
        - conversion_rates
        properties:
          base_code:
            type: string
            description: The ISO 4217 currency code used as the base for rates
            example: USD
          conversion_rates:
            $ref: '#/components/schemas/ConversionRates'
    TimestampFields:
      type: object
      description: Update timestamp fields included in rate responses
      properties:
        time_last_update_unix:
          type: integer
          format: int64
          description: Unix epoch timestamp of the last exchange rate update
          example: 1585267200
        time_last_update_utc:
          type: string
          description: UTC datetime string of the last exchange rate update
          example: Fri, 27 Mar 2020 00:00:00 +0000
        time_next_update_unix:
          type: integer
          format: int64
          description: Unix epoch timestamp of the next scheduled exchange rate update
          example: 1585353600
        time_next_update_utc:
          type: string
          description: UTC datetime string of the next scheduled exchange rate update
          example: Sat, 28 Mar 2020 00:00:00 +0000
    PairConversionResponse:
      allOf:
      - $ref: '#/components/schemas/PairRateResponse'
      - type: object
        required:
        - conversion_result
        properties:
          conversion_result:
            type: number
            format: double
            description: The result of converting the specified amount at the conversion_rate
            example: 5.8884
    ErrorResponse:
      type: object
      required:
      - result
      - error-type
      properties:
        result:
          $ref: '#/components/schemas/ResultError'
        error-type:
          type: string
          description: Machine-readable error code
          enum:
          - unsupported-code
          - malformed-request
          - invalid-key
          - inactive-account
          - quota-reached
          example: invalid-key
    BaseMetadata:
      type: object
      description: Common metadata fields returned in all successful responses
      properties:
        result:
          $ref: '#/components/schemas/ResultSuccess'
        documentation:
          type: string
          format: uri
          description: Link to the API documentation
          example: https://www.exchangerate-api.com/docs
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use
          example: https://www.exchangerate-api.com/terms
    ResultError:
      type: string
      enum:
      - error
      description: Indicates the request failed
    HistoricalRatesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseMetadata'
      - type: object
        required:
        - result
        - base_code
        - year
        - month
        - day
        - conversion_rates
        properties:
          base_code:
            type: string
            description: The ISO 4217 currency code used as the base for rates
            example: USD
          year:
            type: integer
            description: The year of the historical data
            example: 2023
          month:
            type: integer
            description: The month of the historical data
            example: 3
          day:
            type: integer
            description: The day of the historical data
            example: 15
          requested_time:
            type: string
            format: date-time
            description: The ISO 8601 timestamp of when data was snapshotted for that date
            example: '2023-03-15T00:00:01+00:00'
          conversion_rates:
            $ref: '#/components/schemas/ConversionRates'
    PairRateResponse:
      allOf:
      - $ref: '#/components/schemas/BaseMetadata'
      - $ref: '#/components/schemas/TimestampFields'
      - type: object
        required:
        - result
        - base_code
        - target_code
        - conversion_rate
        properties:
          base_code:
            type: string
            description: The ISO 4217 source currency code
            example: EUR
          target_code:
            type: string
            description: The ISO 4217 target currency code
            example: GBP
          conversion_rate:
            type: number
            format: double
            description: The exchange rate from base to target currency
            example: 0.8412
    ConversionRates:
      type: object
      description: 'Object mapping ISO 4217 currency codes to their exchange rate values relative to the base currency

        '
      additionalProperties:
        type: number
        format: double
      example:
        USD: 1
        EUR: 0.8876
        GBP: 0.7901
        JPY: 107.53
    ResultSuccess:
      type: string
      enum:
      - success
      description: Indicates the request was successful
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass API key as a Bearer token in the Authorization header (e.g. Authorization: Bearer YOUR-API-KEY). When using this method, omit the API key from the URL path. The path-key endpoints do not use a security scheme in the OpenAPI sense; the {apiKey} path parameter serves as the credential.

        '
externalDocs:
  description: ExchangeRate-API Documentation
  url: https://www.exchangerate-api.com/docs/overview