{"openapi":"3.1.0","info":{"title":"Stock Index Seasonality API","version":"1.0.0","description":"The calendar patterns equity traders position around — \"Sell in May\", the Santa Claus rally, the September swoon — computed live from ~10 years of Yahoo Finance monthly data across the world's major stock indices (no key, nothing stored). Equities have well-documented seasonal tendencies, and this measures them directly: for each index it takes a decade of monthly returns, groups them by calendar month, and returns the average return in each of the twelve months, the share of years that month was positive (the win rate), and the historically strongest and weakest months. The seasonality endpoint returns one index's full 12-month seasonal profile plus the current month's historical bias. The month endpoint flips it around: for a calendar month it ranks every index by its historical average return, so you can see which markets are seasonally strong or weak right now. The indices endpoint lists what is covered, from the S&P 500, Nasdaq, Dow and Russell to the DAX, FTSE, CAC, Euro Stoxx, Nikkei and Hang Seng. The equity-index seasonality / calendar-pattern cut — distinct from the FX, commodity and crypto seasonality APIs, the index price feed and the constituent APIs.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/indexseasonality-api","description":"oanor gateway"}],"tags":[{"name":"Seasonality"},{"name":"Month"},{"name":"Indices"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/seasonality":{"get":{"operationId":"get_v1_seasonality","tags":["Seasonality"],"summary":"One index 12-month seasonal profile with best/worst month and current bias","description":"","parameters":[{"name":"index","in":"query","required":true,"description":"Key or alias (see /v1/indices)","schema":{"type":"string"},"example":"sp500"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"name":"S&P 500","note":"Average month-over-month return in each calendar month over ~10 years, with win_rate_pct (share of years that month was positive) and the sample size (years). Captures effects like Sell-in-May and the year-end rally. Seasonal tendencies are statistical, not guarantees. Not financial advice.","index":"sp500","months":[{"month":"January","years":10,"month_num":1,"win_rate_pct":70,"avg_return_pct":2.11},{"month":"February","years":10,"month_num":2,"win_rate_pct":40,"avg_return_pct":-0.4},{"month":"March","years":10,"month_num":3,"win_rate_pct":50,"avg_return_pct":-1.22},{"month":"April","years":10,"month_num":4,"win_rate_pct":70,"avg_return_pct":2.2},{"month":"May","years":10,"month_num":5,"win_rate_pct":90,"avg_return_pct":2.02},{"month":"June","years":11,"month_num":6,"win_rate_pct":73,"avg_return_pct":1.18},{"month":"July","years":9,"month_num":7,"win_rate_pct":100,"avg_return_pct":3.51},{"month":"August","years":10,"month_num":8,"win_rate_pct":70,"avg_return_pct":1.06},{"month":"September","years":10,"month_num":9,"win_rate_pct":50,"avg_return_pct":-1.61},{"month":"October","years":10,"month_num":10,"win_rate_pct":50,"avg_return_pct":0.79},{"month":"November","years":10,"month_num":11,"win_rate_pct":90,"avg_return_pct":4.31},{"month":"December","years":10,"month_num":12,"win_rate_pct":60,"avg_return_pct":-0.23}],"region":"us","source":"Yahoo Finance","best_month":{"month":"November","win_rate_pct":90,"avg_return_pct":4.31},"worst_month":{"month":"September","win_rate_pct":50,"avg_return_pct":-1.61},"current_month":{"bias":"historically bullish","month":"June","win_rate_pct":73,"avg_return_pct":1.18}},"meta":{"timestamp":"2026-06-12T10:35:15.362Z","request_id":"4ff402c3-b8fa-4e6e-9f29-daddfa4f6a36"},"status":"ok","message":"Seasonality retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/month":{"get":{"operationId":"get_v1_month","tags":["Month"],"summary":"Every index ranked by historical average return in a calendar month","description":"","parameters":[{"name":"month","in":"query","required":false,"description":"1-12 or month name (default current)","schema":{"type":"string"},"example":"December"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Every index ranked by its historical average return in December over ~10 years, seasonally strongest first.","month":"December","source":"Yahoo Finance","indices":[{"name":"Hang Seng (Hong Kong)","index":"hang_seng","years":10,"region":"asia","win_rate_pct":80,"avg_return_pct":3.21},{"name":"Euro Stoxx 50","index":"euro_stoxx50","years":10,"region":"europe","win_rate_pct":60,"avg_return_pct":2.2},{"name":"DAX (Germany)","index":"dax","years":10,"region":"europe","win_rate_pct":70,"avg_return_pct":2.06},{"name":"FTSE 100 (UK)","index":"ftse100","years":10,"region":"europe","win_rate_pct":70,"avg_return_pct":1.99},{"name":"CAC 40 (France)","index":"cac40","years":10,"region":"europe","win_rate_pct":50,"avg_return_pct":1.7},{"name":"Nikkei 225 (Japan)","index":"nikkei225","years":10,"region":"asia","win_rate_pct":60,"avg_return_pct":1.58},{"name":"India (Nifty/MSCI)","index":"india","years":10,"region":"asia","win_rate_pct":40,"avg_return_pct":0.73},{"name":"Emerging Markets","index":"emerging_markets","years":10,"region":"global","win_rate_pct":60,"avg_return_pct":0.24},{"name":"Dow Jones","index":"dow","years":10,"region":"us","win_rate_pct":70,"avg_return_pct":0.19},{"name":"S&P 500","index":"sp500","years":10,"region":"us","win_rate_pct":60,"avg_return_pct":-0.23},{"name":"S&P MidCap 400","index":"sp_midcap","years":10,"region":"us","win_rate_pct":50,"avg_return_pct":-0.23},{"name":"Nasdaq 100","index":"nasdaq100","years":10,"region":"us","win_rate_pct":70,"avg_return_pct":-0.27},{"name":"Russell 2000","index":"russell2000","years":10,"region":"us","win_rate_pct":50,"avg_return_pct":-0.28},{"name":"Brazil (Bovespa/MSCI)","index":"brazil","years":10,"region":"americas","win_rate_pct":40,"avg_return_pct":-0.55}],"scanned":14,"weakest":[{"name":"Brazil (Bovespa/MSCI)","win_rate_pct":40,"avg_return_pct":-0.55},{"name":"Russell 2000","win_rate_pct":50,"avg_return_pct":-0.28},{"name":"Nasdaq 100","win_rate_pct":70,"avg_return_pct":-0.27},{"name":"S&P MidCap 400","win_rate_pct":50,"avg_return_pct":-0.23},{"name":"S&P 500","win_rate_pct":60,"avg_return_pct":-0.23}],"month_num":12,"strongest":[{"name":"Hang Seng (Hong Kong)","win_rate_pct":80,"avg_return_pct":3.21},{"name":"Euro Stoxx 50","win_rate_pct":60,"avg_return_pct":2.2},{"name":"DAX (Germany)","win_rate_pct":70,"avg_return_pct":2.06},{"name":"FTSE 100 (UK)","win_rate_pct":70,"avg_return_pct":1.99},{"name":"CAC 40 (France)","win_rate_pct":50,"avg_return_pct":1.7}]},"meta":{"timestamp":"2026-06-12T10:35:15.648Z","request_id":"26a7de1e-a75d-49a4-bd8d-f7d0e2818a07"},"status":"ok","message":"Month seasonality retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/indices":{"get":{"operationId":"get_v1_indices","tags":["Indices"],"summary":"Supported indices and regions","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Supported stock indices. Pass key/alias as index= to /v1/seasonality, or month= (1-12 or name) to /v1/month.","count":14,"source":"Yahoo Finance","indices":[{"key":"sp500","name":"S&P 500","region":"us"},{"key":"nasdaq100","name":"Nasdaq 100","region":"us"},{"key":"dow","name":"Dow Jones","region":"us"},{"key":"russell2000","name":"Russell 2000","region":"us"},{"key":"sp_midcap","name":"S&P MidCap 400","region":"us"},{"key":"dax","name":"DAX (Germany)","region":"europe"},{"key":"ftse100","name":"FTSE 100 (UK)","region":"europe"},{"key":"cac40","name":"CAC 40 (France)","region":"europe"},{"key":"euro_stoxx50","name":"Euro Stoxx 50","region":"europe"},{"key":"nikkei225","name":"Nikkei 225 (Japan)","region":"asia"},{"key":"hang_seng","name":"Hang Seng (Hong Kong)","region":"asia"},{"key":"emerging_markets","name":"Emerging Markets","region":"global"},{"key":"india","name":"India (Nifty/MSCI)","region":"asia"},{"key":"brazil","name":"Brazil (Bovespa/MSCI)","region":"americas"}],"regions":["us","europe","asia","americas","global"]},"meta":{"timestamp":"2026-06-12T10:35:15.729Z","request_id":"2360ee1c-732a-403a-b32e-b0b6d5822ad4"},"status":"ok","message":"Indices retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Service metadata","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"index is a key/alias (sp500, nasdaq100, dax, nikkei225; see /v1/indices). month is 1-12 or a name (default current month). Averages use ~10 years of monthly returns grouped by calendar month. Read fresh per call, nothing cached.","source":"Yahoo Finance monthly index data, ~10y range, live","regions":["us","europe","asia","americas","global"],"service":"indexseasonality-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/month":"Every index ranked by historical average return in a calendar month (month=December).","GET /v1/indices":"The supported indices and regions.","GET /v1/seasonality":"One index's 12-month seasonal profile with best/worst month and current-month bias (index=sp500)."},"description":"Stock index seasonality — the calendar patterns equity traders position around (Sell in May, the Santa rally), from ~10 years of Yahoo Finance monthly data across the world's major indices (no key, nothing stored). seasonality returns one index's 12-month seasonal profile (average return and win rate per calendar month, best/worst month, current-month bias). month ranks every index by its historical average return in a calendar month. indices lists what is covered. The equity-index seasonality / calendar-pattern cut — distinct from the FX, commodity and crypto seasonality APIs, the index price feed and constituent APIs.","indices_covered":14,"upstream_status":"ok","sp500_best_month":"November"},"meta":{"timestamp":"2026-06-12T10:35:15.839Z","request_id":"5034643d-5b68-47ad-88f8-61ef07d90776"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":840,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1042,"monthly_call_quota":19200,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3144,"monthly_call_quota":93500,"rps_limit":16,"hard_limit":true},{"slug":"business","name":"Business","price_cents_month":7280,"monthly_call_quota":512000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/indexseasonality-api"}