Skip to content
StatAlphaDocumentation

SEASONALITY — Weekday / Week / Month Patterns

The Seasonality module analyzes how price performance and trading volume vary across weekdays, calendar weeks, and months.
It helps uncover recurring behavioral patterns and long-term performance tendencies that support bias calibration and time-based trade alignment.


  • Aggregates daily data into higher-order time segments: weekday, week (ISO 1–52), and month (1–12).
  • Calculates:
    • Average and median return (%)
    • Green-rate (% of positive closes)
    • Average volume
  • Enables detection of statistically relevant patterns such as:
    • “Fridays tend to close green 63% of the time”
    • “Week 37 historically shows negative average returns”
    • “April and November are statistically strong months”

Parameter Type Description
symbol string Asset symbol (e.g., AAPL, BTCUSD)
start_date / end_date string Custom range (YYYY-MM-DD)
time_window string Predefined relative range (e.g., 3M, 6M, 12M, 24M, 5Y)
include_extended_hours bool Include pre-/post-market data
type string One of: weekday, week, month (for /top endpoint)
direction string Sorting direction: top or bottom (for /top endpoint)
sort_by string Field to sort by (e.g., avg_return_pct, median_return_pct)
limit int Number of results for /top endpoint

Endpoint Description
GET /stats/seasonality/weekday Groups returns by weekday (Monday–Friday) and calculates return/volume stats
GET /stats/seasonality/week Aggregates by ISO week number (1–52/53)
GET /stats/seasonality/month Aggregates by calendar month (1–12)
GET /stats/seasonality/top Lists top or worst-performing weekdays/weeks/months
GET /stats/seasonality/summary Returns overall strongest and weakest weekday, week, and month
GET /stats/seasonality/doc Field-level documentation for all endpoints

Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/seasonality/weekday?symbol=AAPL&time_window=12M"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/seasonality/month?symbol=AAPL&time_window=5Y"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/seasonality/top?symbol=AAPL&type=week&direction=top&sort_by=avg_return_pct&limit=5"

{
"symbol": "AAPL",
"used_field": "median_return_pct",
"summary": {
"best_weekday": {"name": "Friday", "median_return_pct": 0.12, "green_days_pct": 62.4},
"worst_weekday": {"name": "Tuesday", "median_return_pct": -0.07, "green_days_pct": 45.1},
"best_week": {"week_number": 46, "median_return_pct": 0.38, "green_weeks_pct": 65.8},
"worst_week": {"week_number": 17, "median_return_pct": -0.22, "green_weeks_pct": 41.3},
"strongest_month": {"month": 11, "median_return_pct": 0.71, "green_months_pct": 69.7},
"weakest_month": {"month": 8, "median_return_pct": -0.32, "green_months_pct": 38.4}
},
"time_window": "12M"
}

Metric Meaning
avg_return_pct / median_return_pct Average or median percentage change during the period
green_days_pct / green_weeks_pct / green_months_pct % of positive closes within that period
avg_volume Mean trading volume across all samples
best/worst weekday/week/month Highest and lowest performing calendar segments
type + direction Used by /top endpoint to rank results

  • Seasonality reveals time-dependent performance biases across different calendar layers.
  • Results help identify strong or weak calendar patterns for backtesting and signal weighting.