Market Calendar Trading Hours

Overview

The Market Calendar API provides information about trading hours for various markets and exchanges. This endpoint is useful for determining whether specific dates are trading days and retrieving the exact market open and close times, accounting for regular trading hours, holidays, and early closes.

API Endpoint

POST /market-calendar/v1/trading-hours

This endpoint returns trading hours information for requested dates.

Request Parameters

The request body should contain a JSON object with the following fields:

{
  "dates": ["2023-11-22", "2023-11-23", "2023-11-24"],
  "country": "US",
  "market": "Equity"
}

• dates: An array of dates in ISO format (YYYY-MM-DD) for which to retrieve trading hours information
• country: The country code for the market (currently only "US" is supported)
• market: The market type (currently only "Equity" is supported)

Note: There is a limit of 100 dates per request.

Response Format

The API returns a JSON object containing trading information for each requested date:

{
  "tradingDays": [
    {
      "date": "2023-11-22",
      "isTradingDay": true,
      "openTime": "09:30",
      "closeTime": "16:00"
    },
    {
      "date": "2023-11-23",
      "isTradingDay": false,
      "openTime": null,
      "closeTime": null
    },
    {
      "date": "2023-11-24",
      "isTradingDay": true,
      "openTime": "09:30",
      "closeTime": "13:00"
    }
  ]
}

Each entry in the tradingDays array contains:

• date: The date in ISO format (YYYY-MM-DD)
• isTradingDay: Boolean indicating whether this is a trading day
• openTime: The market open time in 24-hour format (HH:MM), or null if not a trading day
• closeTime: The market close time in 24-hour format (HH:MM), or null if not a trading day

For US equity markets, standard trading hours are 9:30 AM to 4:00 PM Eastern Time. Early close days (such as before holidays) typically close at 1:00 PM Eastern Time.

Example Usage

Checking Trading Days for a Month

import requests
import datetime

# Generate dates for a month
start_date = datetime.date(2023, 12, 1)
dates = [(start_date + datetime.timedelta(days=i)).isoformat() for i in range(31)]

response = requests.post(
    "https://q-api.example-customer.mesosim.io/market-calendar/v1/trading-hours",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "dates": dates,
        "country": "US",
        "market": "Equity"
    }
)

trading_days = response.json()["tradingDays"]

# Filter to just trading days
actual_trading_days = [day for day in trading_days if day["isTradingDay"]]
print(f"Number of trading days in December 2023: {len(actual_trading_days)}")

# Check for early close days
early_close_days = [day for day in actual_trading_days if day["closeTime"] != "16:00"]
for day in early_close_days:
    print(f"Early close on {day['date']} at {day['closeTime']}")

Using Trading Hours for Scheduling

import requests
from datetime import datetime, timedelta

# Get trading hours for the next 5 days
today = datetime.now().date()
dates = [(today + timedelta(days=i)).isoformat() for i in range(5)]

response = requests.post(
    "https://q-api.example-customer.mesosim.io/market-calendar/v1/trading-hours",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "dates": dates,
        "country": "US",
        "market": "Equity"
    }
)

trading_days = response.json()["tradingDays"]

# Schedule operations for the next trading day
next_trading_day = next((day for day in trading_days if day["isTradingDay"]), None)

if next_trading_day:
    date = next_trading_day["date"]
    open_time = next_trading_day["openTime"]
    close_time = next_trading_day["closeTime"]
    
    print(f"Next trading day: {date}")
    print(f"Market open: {open_time}")
    print(f"Market close: {close_time}")
    
    # Schedule operations 30 minutes after open and 30 minutes before close
    open_plus_30 = datetime.strptime(f"{date} {open_time}", "%Y-%m-%d %H:%M") + timedelta(minutes=30)
    close_minus_30 = datetime.strptime(f"{date} {close_time}", "%Y-%m-%d %H:%M") - timedelta(minutes=30)
    
    print(f"Schedule morning operation at: {open_plus_30.strftime('%Y-%m-%d %H:%M')}")
    print(f"Schedule afternoon operation at: {close_minus_30.strftime('%Y-%m-%d %H:%M')}")
else:
    print("No trading days in the next 5 days")

Practical Applications

• Algorithmic Trading: Ensure trading systems only operate during market hours and properly handle holidays and early closes
• Reporting: Generate end-of-day reports at the appropriate time
• Walkforward: Filter historical data to include only valid trading days and times

Notes and Limitations

• The API currently supports US equity markets only
• The API returns regular market hours and does not include extended hours trading sessions
• Trading hours are returned in 24-hour format and do not include timezone information (US equity market hours are in Eastern Time)
• There is a limit of 100 dates per request; for larger date ranges, break requests into batches
• The API accounts for market holidays and early closes based on exchange calendars
• Non-trading days (weekends, holidays) will have null values for open and close times