openapi: 3.0.3
info:
  title: Barchart OnDemand API
  description: >-
    The Barchart OnDemand API is a commercially licensed market-data and
    commodity-data service hosted at https://ondemand.websol.barchart.com.
    It exposes a broad catalog of REST endpoints for quotes, historical time
    series, reference/instrument metadata, futures and options, fundamentals,
    corporate actions, cryptocurrencies, physical-commodity and agricultural
    data, technicals, news, and weather. Every call is authenticated with an
    `apikey` query parameter issued by Barchart, and each endpoint responds in
    JSON, XML, or CSV selected by the path suffix (for example
    `/getQuote.json`, `/getQuote.xml`, `/getQuote.csv`); GET, POST, and SOAP
    transports are supported.

    ACCESS NOTE - Barchart OnDemand is subscription and enterprise gated. The
    endpoint names, HTTP method, `apikey` auth, format suffixes, and the
    documented request parameters below are taken from Barchart's public
    OnDemand documentation and are accurate. Because request quotas, the exact
    field catalogs, and full response payloads are entitlement-specific and
    not publicly published in machine-readable form, the response schemas in
    this document are HONESTLY MODELED (endpointsModeled) rather than captured
    from live authenticated responses. Field sets returned depend on your
    Barchart data license.
  version: '1.0'
  contact:
    name: Barchart OnDemand
    url: https://www.barchart.com/ondemand/api
  x-access-model: subscription-and-enterprise (apikey required; contact sales / free trial)
  x-endpoints-modeled: true
servers:
- url: https://ondemand.websol.barchart.com
  description: Barchart OnDemand production host
security:
- apiKeyQuery: []
tags:
- name: Quotes
  description: Real-time, delayed, and end-of-day price quotes.
- name: History
  description: Historical tick, minute, and end-of-day time series.
- name: Reference & Equities
  description: Instrument metadata and bulk equities by exchange.
- name: Futures & Options
  description: Futures and options market data and analytics.
- name: Fundamentals
  description: Company profiles and financial statements.
- name: Corporate Actions & Earnings
  description: Splits, dividends, earnings, and calendars.
- name: Cryptocurrency
  description: Spot crypto quotes and history.
- name: Commodities & Agriculture
  description: Grain bids, commodity statistics, fuel, and crop data.
- name: Technicals & Charts
  description: Technical studies, signals, and chart images.
- name: News & Filings
  description: Financial news and SEC filings.
- name: Weather
  description: Current conditions and forecasts.
paths:
  /getQuote.json:
    get:
      operationId: getQuote
      tags:
      - Quotes
      summary: Get quotes
      description: >-
        Request real-time, delayed, or end-of-day price data by symbol for
        stocks, indexes, mutual funds, ETFs, futures, forex, or
        cryptocurrencies. Multiple comma-separated symbols are supported, as is
        futures notation such as `ESZ25`, `ES*0` (active), and `ES^F` (all
        contracts).
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        description: One or more comma-separated instrument symbols.
        schema:
          type: string
        example: AAPL,GOOG,ESZ25
      - name: fields
        in: query
        required: false
        description: Comma- or semicolon-delimited list of additional fields to return.
        schema:
          type: string
        example: fiftyTwoWkHigh,fiftyTwoWkLow
      responses:
        '200':
          $ref: '#/components/responses/QuoteResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getQuoteEod.json:
    get:
      operationId: getQuoteEod
      tags:
      - Quotes
      summary: Get end-of-day quotes
      description: End-of-day price data by exchange and symbol.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      - name: exchange
        in: query
        required: false
        description: Exchange acronym to scope the request.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/QuoteResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getHistory.json:
    get:
      operationId: getHistory
      tags:
      - History
      summary: Get historical time series
      description: >-
        Historical time series (tick, minute bars, or end-of-day) for stocks,
        indexes, mutual funds, ETFs, futures, forex, or crypto, with daily,
        weekly, monthly, quarterly, yearly and nearest/continuation variants.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbol
        in: query
        required: true
        description: A single instrument symbol.
        schema:
          type: string
        example: IBM
      - name: type
        in: query
        required: true
        description: >-
          Time series type, e.g. ticks, minutes, nearbyMinutes, formTMinutes,
          daily, dailyNearest, dailyContinue, weekly, monthly, quarterly,
          yearly (and their Nearest/Continue variants).
        schema:
          type: string
          example: daily
      - name: startDate
        in: query
        required: false
        description: Inclusive start date/time (YYYYMMDD or YYYYMMDDHHmmss).
        schema:
          type: string
      - name: endDate
        in: query
        required: false
        description: Inclusive end date/time.
        schema:
          type: string
      - name: maxRecords
        in: query
        required: false
        description: Maximum number of records to return.
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/HistoryResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getEquitiesByExchange.json:
    get:
      operationId: getEquitiesByExchange
      tags:
      - Reference & Equities
      summary: Get all equities by exchange
      description: Returns market data for all equities on a given exchange in a single query.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: exchange
        in: query
        required: true
        description: Exchange acronym (e.g. NYSE, NASDAQ, AMEX).
        schema:
          type: string
        example: NYSE
      - name: fields
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/QuoteResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getInstrumentDefinition.json:
    get:
      operationId: getInstrumentDefinition
      tags:
      - Reference & Equities
      summary: Get instrument definitions
      description: Instrument metadata by symbol, exchange, or MIC (names, codes, tick increments).
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: false
        schema:
          type: string
      - name: exchange
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getFuturesOptions.json:
    get:
      operationId: getFuturesOptions
      tags:
      - Futures & Options
      summary: Get futures options
      description: >-
        Intraday options data on futures - strike price, volume, open interest,
        implied volatility and greeks - for a given root futures symbol.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: root
        in: query
        required: true
        description: Root futures symbol.
        schema:
          type: string
        example: CL
      - name: fields
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getFuturesByExchange.json:
    get:
      operationId: getFuturesByExchange
      tags:
      - Futures & Options
      summary: Get futures by exchange
      description: Real-time, delayed, or end-of-day futures data for all contracts on an exchange.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: exchange
        in: query
        required: true
        schema:
          type: string
        example: CME
      responses:
        '200':
          $ref: '#/components/responses/QuoteResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getOptionsScreener.json:
    get:
      operationId: getOptionsScreener
      tags:
      - Futures & Options
      summary: Screen equity/ETF options
      description: Screen equity and ETF options using filters to surface unusual activity.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: baseSymbol
        in: query
        required: false
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getProfile.json:
    get:
      operationId: getProfile
      tags:
      - Fundamentals
      summary: Get company profile
      description: Company information - sector, industry, CEO, earnings, P/E ratio, and address.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
        example: MSFT
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getFinancialHighlights.json:
    get:
      operationId: getFinancialHighlights
      tags:
      - Fundamentals
      summary: Get financial highlights
      description: Key financial metrics such as market cap, revenue, net income, and EPS.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getIncomeStatements.json:
    get:
      operationId: getIncomeStatements
      tags:
      - Fundamentals
      summary: Get income statements
      description: Public-company income statement data.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      - name: frequency
        in: query
        required: false
        description: annual or quarter.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getRatings.json:
    get:
      operationId: getRatings
      tags:
      - Fundamentals
      summary: Get analyst ratings
      description: Analyst ratings from strong buy through strong sell.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getCorporateActions.json:
    get:
      operationId: getCorporateActions
      tags:
      - Corporate Actions & Earnings
      summary: Get corporate actions
      description: Splits, dividends, and earnings data for the requested symbols.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        description: splits, dividends, or earnings.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getEarningsCalendar.json:
    get:
      operationId: getEarningsCalendar
      tags:
      - Corporate Actions & Earnings
      summary: Get earnings calendar
      description: Upcoming earnings totals and data by date.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: date
        in: query
        required: false
        description: Calendar date (YYYYMMDD).
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getCrypto.json:
    get:
      operationId: getCrypto
      tags:
      - Cryptocurrency
      summary: Get crypto quotes
      description: Spot-market cryptocurrency price data (Bitcoin, Ethereum, Ripple, Litecoin, etc.).
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
        example: ^BTCUSD,^ETHUSD
      responses:
        '200':
          $ref: '#/components/responses/QuoteResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getCryptoHistory.json:
    get:
      operationId: getCryptoHistory
      tags:
      - Cryptocurrency
      summary: Get crypto history
      description: Historical price data for spot cryptocurrencies.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbol
        in: query
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/HistoryResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getGrainBids.json:
    get:
      operationId: getGrainBids
      tags:
      - Commodities & Agriculture
      summary: Get grain cash bids
      description: Cash bid data for the 30 closest grain locations to a point.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: zipCode
        in: query
        required: false
        description: US zip code used to find nearby grain locations.
        schema:
          type: string
      - name: commodities
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getCmdtyStats.json:
    get:
      operationId: getCmdtyStats
      tags:
      - Commodities & Agriculture
      summary: Get commodity statistics
      description: Fundamentals, commodity statistics, and economic data with historical records.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getFuelPrices.json:
    get:
      operationId: getFuelPrices
      tags:
      - Commodities & Agriculture
      summary: Get fuel prices
      description: Refined fuel price data and reference data by location or coordinates.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: zipCode
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getTechnicals.json:
    get:
      operationId: getTechnicals
      tags:
      - Technicals & Charts
      summary: Get technicals
      description: Technical data and statistics for equities, indices, futures, and currencies.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getSignal.json:
    get:
      operationId: getSignal
      tags:
      - Technicals & Charts
      summary: Get technical signal
      description: Technical Opinion/Signal (buy, sell, hold) based on aggregated indicators.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getNews.json:
    get:
      operationId: getNews
      tags:
      - News & Filings
      summary: Get news
      description: News headlines, articles, and photos by source, category, or keyword.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: sources
        in: query
        required: false
        schema:
          type: string
      - name: symbols
        in: query
        required: false
        schema:
          type: string
      - name: maxRecords
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getSECFilings.json:
    get:
      operationId: getSECFilings
      tags:
      - News & Filings
      summary: Get SEC filings
      description: Quarterly, annual, and regulatory SEC filings.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: symbols
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getWeather.json:
    get:
      operationId: getWeather
      tags:
      - Weather
      summary: Get weather
      description: Current conditions, forecasts, and maps by zip code.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: zipCode
        in: query
        required: true
        schema:
          type: string
        example: '60654'
      - name: fields
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GenericResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: >-
        Barchart-issued API key passed as the `apikey` query parameter on every
        request (for example `?apikey=YOUR_API_KEY`). Keys are provisioned with
        a Barchart OnDemand subscription or enterprise agreement.
  parameters:
    ApiKey:
      name: apikey
      in: query
      required: true
      description: Barchart-issued API key.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or unentitled API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    QuoteResults:
      description: >-
        A status envelope plus an array of quote records. Field set depends on
        your data entitlement (modeled).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/Status'
              results:
                type: array
                items:
                  $ref: '#/components/schemas/Quote'
    HistoryResults:
      description: A status envelope plus an array of historical bars (modeled).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/Status'
              results:
                type: array
                items:
                  $ref: '#/components/schemas/Bar'
    GenericResults:
      description: >-
        A status envelope plus an array of result objects whose fields vary by
        endpoint and entitlement (modeled).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/Status'
              results:
                type: array
                items:
                  type: object
                  additionalProperties: true
  schemas:
    Status:
      type: object
      description: Standard Barchart OnDemand status envelope.
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: Success.
    Quote:
      type: object
      description: Modeled quote record; the exact fields returned depend on entitlement.
      properties:
        symbol:
          type: string
        name:
          type: string
        exchange:
          type: string
        lastPrice:
          type: number
        netChange:
          type: number
        percentChange:
          type: number
        open:
          type: number
        high:
          type: number
        low:
          type: number
        volume:
          type: integer
        tradeTimestamp:
          type: string
          format: date-time
      additionalProperties: true
    Bar:
      type: object
      description: Modeled historical bar.
      properties:
        symbol:
          type: string
        timestamp:
          type: string
          format: date-time
        tradingDay:
          type: string
        open:
          type: number
        high:
          type: number
        low:
          type: number
        close:
          type: number
        volume:
          type: integer
        openInterest:
          type: integer
      additionalProperties: true