ExchangeRate-API Pair Conversion API

openapi: 3.1.0
info:
  title: ExchangeRate-API
  description: >-
    ExchangeRate-API is a currency exchange rate API providing authoritative
    daily and intraday foreign exchange rates for 161 currencies. The v6 API
    surface includes Standard (Latest) rates, Pair conversion, Enriched data
    (locale, symbol, flag), Historical rates back to 1990, Supported codes,
    and an API request Quota endpoint. A separate no-key Open Access endpoint
    (open.er-api.com) provides once-daily rates with attribution.
  version: 6.0.0
  termsOfService: https://www.exchangerate-api.com/terms
  contact:
    name: ExchangeRate-API Support
    url: https://www.exchangerate-api.com/contact
    email: [email protected]
  license:
    name: Proprietary
    url: https://www.exchangerate-api.com/terms
servers:
  - url: https://v6.exchangerate-api.com/v6
    description: ExchangeRate-API v6 Production (API key required)
  - url: https://open.er-api.com/v6
    description: ExchangeRate-API Open Access (no API key, attribution required)
security:
  - apiKeyPath: []
tags:
  - name: Latest Rates
    description: Standard endpoint returning latest exchange rates from a base currency to all supported currencies.
  - name: Pair Conversion
    description: Direct currency-to-currency exchange rate and optional amount conversion.
  - name: Enriched Data
    description: Pair conversion enriched with target currency locale, name, symbol, and flag (Business / Volume plans only).
  - name: Historical Rates
    description: Historical exchange rates for a specific date back to 1990 (Pro / Business / Volume plans only).
  - name: Supported Codes
    description: List of all supported ISO 4217 currency codes with their full names.
  - name: Quota
    description: Inspect the remaining request quota for the API key.
  - name: Open Access
    description: Free no-key endpoint with once-daily rates and attribution requirement.
paths:
  /{api_key}/latest/{base_code}:
    get:
      tags:
        - Latest Rates
      summary: Get Latest Rates
      description: >-
        Returns the latest exchange rates from a given base currency to all
        supported currencies. Update frequency depends on plan tier (daily on
        Free, hourly on Pro, every 5 minutes on Business / Volume).
      operationId: getLatestRates
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
      responses:
        '200':
          description: Successful response with conversion rates for the base currency.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
        '400':
          description: Error response (malformed request, invalid key, etc.).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/pair/{base_code}/{target_code}:
    get:
      tags:
        - Pair Conversion
      summary: Get Pair Conversion Rate
      description: Returns the exchange rate between a base and a target currency.
      operationId: getPairConversion
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
        - $ref: '#/components/parameters/TargetCode'
      responses:
        '200':
          description: Successful response with conversion rate for the currency pair.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/pair/{base_code}/{target_code}/{amount}:
    get:
      tags:
        - Pair Conversion
      summary: Get Pair Conversion With Amount
      description: Returns the exchange rate between a base and a target currency along with the converted amount.
      operationId: getPairConversionWithAmount
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
        - $ref: '#/components/parameters/TargetCode'
        - $ref: '#/components/parameters/Amount'
      responses:
        '200':
          description: Successful response with conversion rate and converted amount.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairAmountResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/enriched/{base_code}/{target_code}:
    get:
      tags:
        - Enriched Data
      summary: Get Enriched Pair Data
      description: >-
        Returns the exchange rate between a base and target currency along with
        enriched target currency metadata (country locale, two-letter country
        code, currency name, display symbol, flag URL). Only available on
        Business and Volume plans.
      operationId: getEnrichedPair
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
        - $ref: '#/components/parameters/TargetCode'
      responses:
        '200':
          description: Successful response with conversion rate and enriched target data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedPairResponse'
        '400':
          description: Error response (may include plan-upgrade-required).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/history/{base_code}/{year}/{month}/{day}:
    get:
      tags:
        - Historical Rates
      summary: Get Historical Rates
      description: >-
        Returns historical exchange rates for the given base currency on the
        specified date. Full currency support from 2021-01-01 onward; 35
        currencies are available from 1990-01-01 to 2020-12-31. Only available
        on Pro, Business, and Volume plans.
      operationId: getHistoricalRates
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Month'
        - $ref: '#/components/parameters/Day'
      responses:
        '200':
          description: Successful response with historical rates for the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
        '400':
          description: Error response (may include no-data-available, plan-upgrade-required).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/history/{base_code}/{year}/{month}/{day}/{amount}:
    get:
      tags:
        - Historical Rates
      summary: Get Historical Rates With Amount
      description: Returns historical exchange rates plus converted amounts for the given base currency on the specified date.
      operationId: getHistoricalRatesWithAmount
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/BaseCode'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Month'
        - $ref: '#/components/parameters/Day'
        - $ref: '#/components/parameters/Amount'
      responses:
        '200':
          description: Successful response with historical rates and converted amounts for the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalAmountsResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/codes:
    get:
      tags:
        - Supported Codes
      summary: Get Supported Codes
      description: Returns an array of all supported ISO 4217 currency codes and their full names.
      operationId: getSupportedCodes
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Successful response containing supported codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedCodesResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/quota:
    get:
      tags:
        - Quota
      summary: Get Request Quota
      description: Returns the plan quota, number of requests remaining in the current billing window, and refresh metadata for the API key.
      operationId: getQuota
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Successful response with current quota information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /latest/{base_code}:
    get:
      tags:
        - Open Access
      summary: Get Open Access Latest Rates
      description: >-
        Returns the latest exchange rates from a base currency via the
        no-API-key Open Access endpoint (https://open.er-api.com/v6). Requires
        attribution back to exchangerate-api.com. Updates once daily and is
        rate limited.
      operationId: getOpenAccessLatest
      servers:
        - url: https://open.er-api.com/v6
      parameters:
        - $ref: '#/components/parameters/BaseCode'
      responses:
        '200':
          description: Successful response with conversion rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAccessResponse'
        '429':
          description: Rate limit exceeded; retry after 20 minutes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    apiKeyPath:
      type: apiKey
      in: path
      name: api_key
      description: ExchangeRate-API uses an API key embedded in the URL path (after /v6/).
  parameters:
    ApiKey:
      name: api_key
      in: path
      required: true
      description: Your ExchangeRate-API dashboard API key.
      schema:
        type: string
    BaseCode:
      name: base_code
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the base currency (e.g. USD).
      schema:
        type: string
        pattern: '^[A-Z]{3}$'
        example: USD
    TargetCode:
      name: target_code
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the target currency (e.g. EUR).
      schema:
        type: string
        pattern: '^[A-Z]{3}$'
        example: EUR
    Amount:
      name: amount
      in: path
      required: true
      description: Decimal amount to convert (xxxx.xxxx format).
      schema:
        type: number
        format: double
        example: 100.0
    Year:
      name: year
      in: path
      required: true
      description: Year for historical data (full four-digit year).
      schema:
        type: integer
        example: 2024
    Month:
      name: month
      in: path
      required: true
      description: Month for historical data (1-12, no leading zero).
      schema:
        type: integer
        minimum: 1
        maximum: 12
        example: 3
    Day:
      name: day
      in: path
      required: true
      description: Day for historical data (1-31, no leading zero).
      schema:
        type: integer
        minimum: 1
        maximum: 31
        example: 15
  schemas:
    LatestRatesResponse:
      type: object
      description: Latest exchange rates response.
      properties:
        result:
          type: string
          description: Status indicator (success).
          example: success
        documentation:
          type: string
          format: uri
          description: Link to the API documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        time_last_update_unix:
          type: integer
          description: Last update time as a Unix timestamp.
        time_last_update_utc:
          type: string
          description: Last update time in UTC.
        time_next_update_unix:
          type: integer
          description: Next scheduled update as a Unix timestamp.
        time_next_update_utc:
          type: string
          description: Next scheduled update in UTC.
        base_code:
          type: string
          description: The base currency requested.
        conversion_rates:
          type: object
          description: Object mapping ISO 4217 currency codes to exchange rates from the base currency.
          additionalProperties:
            type: number
    PairResponse:
      type: object
      description: Pair conversion response without amount.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the API documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        time_last_update_unix:
          type: integer
          description: Last update Unix timestamp.
        time_last_update_utc:
          type: string
          description: Last update in UTC.
        time_next_update_unix:
          type: integer
          description: Next update Unix timestamp.
        time_next_update_utc:
          type: string
          description: Next update in UTC.
        base_code:
          type: string
          description: Supplied base currency.
        target_code:
          type: string
          description: Supplied target currency.
        conversion_rate:
          type: number
          description: Exchange rate between base and target.
    PairAmountResponse:
      allOf:
        - $ref: '#/components/schemas/PairResponse'
        - type: object
          description: Pair conversion with additional converted amount.
          properties:
            conversion_result:
              type: number
              description: Result of converting the requested amount at the current rate.
    EnrichedPairResponse:
      allOf:
        - $ref: '#/components/schemas/PairResponse'
        - type: object
          description: Pair conversion enriched with target currency metadata.
          properties:
            target_data:
              type: object
              description: Enriched data for the target currency.
              properties:
                locale:
                  type: string
                  description: Country / locale name associated with the currency.
                two_letter_code:
                  type: string
                  description: Two-letter country code (ISO 3166-1 alpha-2).
                currency_name:
                  type: string
                  description: Full currency name.
                currency_name_short:
                  type: string
                  description: Short currency name.
                display_symbol:
                  type: string
                  description: Unicode hex reference for the currency symbol.
                flag_url:
                  type: string
                  format: uri
                  description: URL to a flag image for the locale.
    HistoricalRatesResponse:
      type: object
      description: Historical rates response for a specific date.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        year:
          type: integer
          description: Year of the historical record.
        month:
          type: integer
          description: Month of the historical record.
        day:
          type: integer
          description: Day of the historical record.
        base_code:
          type: string
          description: Base currency for the rates.
        conversion_rates:
          type: object
          description: Mapping of ISO 4217 currency codes to historical exchange rates.
          additionalProperties:
            type: number
    HistoricalAmountsResponse:
      type: object
      description: Historical rates with converted amounts.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        year:
          type: integer
          description: Year of the historical record.
        month:
          type: integer
          description: Month of the historical record.
        day:
          type: integer
          description: Day of the historical record.
        base_code:
          type: string
          description: Base currency for the rates.
        requested_amount:
          type: number
          description: Amount supplied for conversion.
        conversion_amounts:
          type: object
          description: Mapping of currency codes to the converted amounts at the historical rate.
          additionalProperties:
            type: number
    SupportedCodesResponse:
      type: object
      description: Supported codes response.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        supported_codes:
          type: array
          description: List of two-element arrays containing the ISO 4217 code and the currency name.
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
    QuotaResponse:
      type: object
      description: Quota response showing remaining requests for the API key.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        plan_quota:
          type: integer
          description: The total monthly request quota for the plan.
        requests_remaining:
          type: integer
          description: Number of requests left until the quota resets.
        refresh_day_of_month:
          type: integer
          description: Day of the month when the quota refreshes.
    OpenAccessResponse:
      type: object
      description: Open Access (no-key) response.
      properties:
        result:
          type: string
          description: Status indicator.
        provider:
          type: string
          format: uri
          description: Provider attribution URL (exchangerate-api.com).
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        time_last_update_unix:
          type: integer
          description: Last update Unix timestamp.
        time_last_update_utc:
          type: string
          description: Last update in UTC.
        time_next_update_unix:
          type: integer
          description: Next update Unix timestamp.
        time_next_update_utc:
          type: string
          description: Next update in UTC.
        time_eol_unix:
          type: integer
          description: End of life Unix timestamp for the response data (if applicable).
        base_code:
          type: string
          description: The base currency requested.
        rates:
          type: object
          description: Object mapping ISO 4217 currency codes to exchange rates from the base currency.
          additionalProperties:
            type: number
    ErrorResponse:
      type: object
      description: Standard error envelope returned when a request cannot be fulfilled.
      properties:
        result:
          type: string
          description: Status indicator (error).
          example: error
        error-type:
          type: string
          description: Machine-readable error code.
          enum:
            - unsupported-code
            - malformed-request
            - invalid-key
            - inactive-account
            - quota-reached
            - plan-upgrade-required
            - no-data-available