openapi: 3.0.3
info:
  title: Currency Convert Range API
  description: CurrencyAPI (currencyapi.com, an Everapi product) is a foreign exchange rate and currency conversion REST API. A single versioned surface at https://api.currencyapi.com/v3 provides the latest exchange rates, historical end-of-day rates back to 1999, time-series ranges with day/hour/quarter-hour/ minute accuracy, value conversion, currency metadata, and account quota status. All endpoints are GET requests authenticated with an API key passed either as an "apikey" HTTP header (recommended) or an "apikey" query parameter. Only successful calls count against your quota; the status endpoint is never counted.
  version: '3.0'
  contact:
    name: CurrencyAPI
    url: https://currencyapi.com
  termsOfService: https://currencyapi.com/terms
servers:
- url: https://api.currencyapi.com/v3
  description: Production
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Range
  description: Time-series exchange rates for a datetime range.
paths:
  /range:
    get:
      operationId: getRangeExchangeRates
      tags:
      - Range
      summary: Range (time-series) exchange rates
      description: Returns exchange rate data for a datetime range in a single call. Accuracy constraints - day covers up to 366 days of history; hour allows a maximum 7-day range up to 3 months back; quarter_hour allows a maximum 24-hour range up to 7 days back; minute allows a maximum 6-hour range up to 7 days back.
      parameters:
      - name: datetime_start
        in: query
        required: true
        description: 'ISO8601 datetime for the start of the range (format: 2022-12-01T00:00:00Z).'
        schema:
          type: string
          format: date-time
          example: '2022-12-01T00:00:00Z'
      - name: datetime_end
        in: query
        required: true
        description: 'ISO8601 datetime for the end of the range (format: 2022-12-31T23:59:59Z).'
        schema:
          type: string
          format: date-time
          example: '2022-12-31T23:59:59Z'
      - name: accuracy
        in: query
        required: false
        description: Accuracy of the time-series data points.
        schema:
          type: string
          enum:
          - day
          - hour
          - quarter_hour
          - minute
          default: day
      - $ref: '#/components/parameters/baseCurrency'
      - $ref: '#/components/parameters/currencies'
      - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Time-series exchange rate data points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RangeResponse'
              example:
                data:
                - datetime: '2022-01-01T23:59:59Z'
                  currencies:
                    AED:
                      code: AED
                      value: 3.67306
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Rate:
      type: object
      properties:
        code:
          type: string
          description: ISO currency code.
          example: EUR
        value:
          type: number
          description: Exchange rate value relative to the base currency.
          example: 0.91234
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    RangeResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              datetime:
                type: string
                format: date-time
              currencies:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Rate'
  responses:
    RateLimited:
      description: Monthly quota or per-minute rate limit exceeded. Inspect the X-RateLimit-Limit-Quota-Minute, X-RateLimit-Limit-Quota-Month, X-RateLimit-Remaining-Quota-Minute, and X-RateLimit-Remaining-Quota-Month response headers to monitor consumption.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation error - incorrect or missing parameters. Failed requests do not count against your quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    currencies:
      name: currencies
      in: query
      required: false
      description: A list of comma-separated currency codes you want to receive (e.g. EUR,USD,CAD). Defaults to all available currencies.
      schema:
        type: string
        example: EUR,USD,CAD
    type:
      name: type
      in: query
      required: false
      description: The type of currency you want to get. Defaults to all types.
      schema:
        type: string
        enum:
        - fiat
        - metal
        - crypto
    baseCurrency:
      name: base_currency
      in: query
      required: false
      description: The base currency to which all results are behaving relative to. Defaults to USD.
      schema:
        type: string
        default: USD
        example: USD
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: API key passed as an HTTP header (recommended).
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as a query parameter (may expose the key in access logs).