openapi: 3.1.0
info:
  title: ExchangeRate Enriched Data 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: contact@exchangerate-api.com
  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: Enriched Data
  description: Pair conversion enriched with target currency locale, name, symbol, and flag (Business / Volume plans only).
paths:
  /{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'
components:
  parameters:
    ApiKey:
      name: api_key
      in: path
      required: true
      description: Your ExchangeRate-API dashboard API key.
      schema:
        type: string
    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
    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
  schemas:
    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
    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.
    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.
  securitySchemes:
    apiKeyPath:
      type: apiKey
      in: path
      name: api_key
      description: ExchangeRate-API uses an API key embedded in the URL path (after /v6/).