openapi: 3.0.3
info:
  title: Open Exchange Rates Convert Time Series API
  description: 'RESTful JSON API delivering live and historical foreign exchange rates for 200+ world and digital currencies. Supports latest rates, historical end-of-day rates, time-series queries, currency conversion, and OHLC data depending on subscription plan. Trusted by over 100,000 organizations globally since 2011, with historical coverage back to January 1, 1999.

    '
  version: '0.7'
  termsOfService: https://openexchangerates.org/terms
  contact:
    name: Open Exchange Rates Support
    url: https://support.openexchangerates.org
    email: support@openexchangerates.org
  license:
    name: Proprietary
    url: https://openexchangerates.org/terms
servers:
- url: https://openexchangerates.org/api
  description: Production API server
security:
- appId: []
tags:
- name: Time Series
  description: Historical time-series data (Enterprise/Unlimited plans)
paths:
  /time-series.json:
    get:
      operationId: getTimeSeries
      summary: Get time-series exchange rates
      description: 'Returns historical exchange rates for a given time period (date range). Rates are provided per day between start and end dates. Available to Enterprise and Unlimited plan subscribers.

        '
      tags:
      - Time Series
      parameters:
      - $ref: '#/components/parameters/app_id'
      - name: start
        in: query
        required: true
        description: Start date for the time series (YYYY-MM-DD format)
        schema:
          type: string
          format: date
          example: '2023-01-01'
      - name: end
        in: query
        required: true
        description: End date for the time series (YYYY-MM-DD format)
        schema:
          type: string
          format: date
          example: '2023-01-31'
      - name: symbols
        in: query
        required: false
        description: Comma-separated 3-letter currency codes to limit results
        schema:
          type: string
          example: EUR,GBP
      - name: base
        in: query
        required: false
        description: Base currency (3-letter ISO code, defaults to USD)
        schema:
          type: string
          example: USD
      - $ref: '#/components/parameters/show_alternative'
      - $ref: '#/components/parameters/prettyprint'
      responses:
        '200':
          description: Successful response with time-series exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    TimeSeriesResponse:
      type: object
      description: Time-series exchange rates response
      properties:
        disclaimer:
          type: string
          description: Legal disclaimer URL
        license:
          type: string
          description: License URL
        start_date:
          type: string
          format: date
          description: Start date of the time series
        end_date:
          type: string
          format: date
          description: End date of the time series
        base:
          type: string
          description: Base currency code
        rates:
          type: object
          description: 'Object mapping YYYY-MM-DD date strings to exchange rate objects

            '
          additionalProperties:
            type: object
            additionalProperties:
              type: number
              format: double
          example:
            '2023-01-01':
              EUR: 0.934567
              GBP: 0.826789
            '2023-01-02':
              EUR: 0.9321
              GBP: 0.825
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        error:
          type: boolean
          description: Always true for error responses
          example: true
        status:
          type: integer
          description: HTTP status code
          example: 401
        message:
          type: string
          description: Short error identifier
          example: invalid_app_id
        description:
          type: string
          description: Detailed human-readable error explanation
          example: Invalid App ID provided. Please sign up at https://openexchangerates.org/signup, or contact support@openexchangerates.org.
  parameters:
    show_alternative:
      name: show_alternative
      in: query
      required: false
      description: 'Set to true to extend returned values with alternative, black market and digital currency rates. Defaults to false.

        '
      schema:
        type: boolean
        default: false
    app_id:
      name: app_id
      in: query
      required: true
      description: Your unique App ID for authentication
      schema:
        type: string
        example: your_app_id_here
    prettyprint:
      name: prettyprint
      in: query
      required: false
      description: 'Set to true to enable human-readable (pretty-printed) JSON output for debugging. Defaults to false to minimize response size.

        '
      schema:
        type: boolean
        default: false
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid App ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameters or unavailable data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too many requests — rate limit or quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    appId:
      type: apiKey
      in: query
      name: app_id
      description: 'Your unique App ID obtained from openexchangerates.org. Required for all endpoints except /currencies.json.

        '