openapi: 3.0.3
info:
  title: Market Data Indices Markets API
  description: The Market Data API delivers real-time and historical U.S. stock, options, and index market data over a simple REST interface. All endpoints are served from https://api.marketdata.app/v1 and return JSON (or CSV) responses. Most endpoints require only a ticker symbol as a path parameter. Requests are authenticated with a Bearer token generated in the Market Data dashboard. Coverage spans stock candles and quotes (single and bulk), corporate earnings and news, full options chains with per-contract quotes, expirations, strikes and OCC symbol lookup, index candles and quotes, and market open/closed status. Note that Market Data may return HTTP 203 Non-Authoritative Information (instead of 200 OK) when a response is served from its caching tier; clients must treat 203 as success.
  version: '1.0'
  contact:
    name: Market Data
    url: https://www.marketdata.app
  termsOfService: https://www.marketdata.app/terms/
servers:
- url: https://api.marketdata.app/v1
  description: Market Data API v1
security:
- bearerAuth: []
tags:
- name: Markets
  description: Reference and status data about the markets covered by Market Data.
paths:
  /markets/status/:
    get:
      operationId: getMarketStatus
      tags:
      - Markets
      summary: Market status
      description: Return whether the market is open or closed for a given date or date range. Responds with "open" for trading days and "closed" for weekends or market holidays. With no parameters, returns the current day's status for the United States market.
      parameters:
      - name: country
        in: query
        required: false
        description: ISO country code for the market to check. Defaults to US.
        schema:
          type: string
      - name: date
        in: query
        required: false
        description: A single date to check.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: The leftmost (earliest) date of the date range.
        schema:
          type: string
      - name: to
        in: query
        required: false
        description: The rightmost (latest) date of the date range.
        schema:
          type: string
      responses:
        '200':
          description: Market open/closed status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatusResponse'
        '203':
          description: Cached market status (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    MarketStatusResponse:
      type: object
      description: Market open/closed status payload.
      properties:
        s:
          type: string
          description: Status of the response.
        date:
          type: array
          items:
            type: integer
        status:
          type: array
          description: One of open, closed, or null for dates outside available data.
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        s:
          type: string
          description: Always error for failed requests.
        errmsg:
          type: string
          description: Human-readable error message.
  responses:
    TooManyRequests:
      description: Credit allocation or simultaneous-request limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or the token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token generated in the Market Data dashboard. Passed as Authorization Bearer YOUR_API_TOKEN. A token may also be supplied via the token query parameter.