Data Dictionary
Plain-English definitions of every field returned by the TradeWave API. All monetary returns are expressed as percentages. Raw prices and OHLCV data are never returned.
Core opportunity fields
Win rate, average/median return and Sharpe use the same completed, direction-aware history. Historical numbers are null when evidence is unavailable or was not evaluated within the bulk endpoint's 50-candidate cap.
Discovery entry dates use the current US market year, with tomorrow also supported at the New Year boundary. Use exact-window analysis for other years. A scan's evidence_failures counts unavailable candidate records even if filters remove them; an incomplete empty scan is not proof that no patterns exist.
| Field | Type | Definition |
|---|---|---|
| symbol | string | Ticker symbol (e.g. "AAPL"). Exactly as used by the market data provider. |
| market | string | Permanent market id ("0".."16"). See the Markets table below. Never renumbered. |
| direction | string | long - the seasonal pattern historically rises over the holding period. short - it historically falls. This is a historically derived seasonal pattern, not a recommendation. |
| entry_date | date | The calendar date the seasonal pattern entry window begins (ISO 8601, e.g. "2026-06-01"). |
| days_out | integer | The inclusive holding period in calendar days, counting the entry date as day 1. The end date is entry_date + (days_out - 1); for example, 22 days means the exit is 21 calendar days after entry. |
| years | string | The requested lookback label, always a string (e.g. "10" or "pe2-5"). Consecutive N includes N prior entry years plus a completed current year when available; election-cycle N selects completed matching occurrences. The actual observation count is years_tested. |
| years_tested | integer or null | Completed observations used by the statistical summary. Null when the record could not be verified; zero means a valid empty cohort. |
| evidence_status | string | verified: completed evidence loaded; no_data: valid empty cohort; unavailable: evidence fetch failed; not_evaluated: beyond the bulk evidence cap. The latter two have null historical statistics. |
| sharpe_ratio | number | The Sharpe ratio of the seasonal pattern over the lookback window. Higher is better. Measures return per unit of volatility across the historical instances. Not annualized - it is specific to the holding period defined by days_out. |
| avg_profit_pct | number | Mean return (in percent) across all historical instances of this pattern. Positive = historically profitable on average. Example: 3.12 means the average instance returned +3.12%. |
| median_profit_pct | number | Median return (in percent) across historical instances. Less sensitive to outlier years than the mean. Useful when a single large year skews avg_profit_pct. |
| win_rate | number (0..1) | Fraction of historical instances that closed in the profitable direction at days_out. Example: 0.78 means 78% of past instances were winners. Does not account for position sizing or slippage. |
ML fields (all tiers, metered per day)
Exact-window ML supports 10-90 calendar days. Unsupported windows do not reserve daily allowance and remain unscored with a duration note, preserving their original positions in batch responses.
New current-condition scores are available from five calendar days before entry through the entry date, using the New York date. Outside that interval, batch rows receive a date note and do not reserve allowance; historical seasonal analysis remains available without ML.
ML fields are available on every tier, metered per day: free 5/day, Dev 100/day, Pro/Business unlimited. ML fields are null when the daily limit is exhausted or the market is not ML-eligible. ML-eligible markets are ids 0, 1, 2, 3, 4, and 11; all other markets (ids 5, 6, 7, 8, 9, 10, 12, 13, and 16) are not ML-eligible.
| Field | Type | Definition |
|---|---|---|
| ml_score | number | AI Return Rank: the model-provided predicted-return percentile, from 0 to 100. It is separate from the probability of profit - use win_prob for that. |
| win_prob | number (0..1) | ML-estimated probability that this opportunity will be a winner at the exit date. Calibrated to historical out-of-sample results. Example: 0.81 = 81% predicted win probability. |
| pred_return | number | ML-predicted return in percent at the exit date. This is the model's point estimate of the expected percentage gain (long) or drop (short). |
| pred_mfe | number | Predicted Maximum Favorable Excursion in percent - the ML model's estimate of the best-case intra-period move in the favorable direction. Useful for sizing and stop placement, not a guarantee. |
Daily pick fields
| Field | Type | Definition |
|---|---|---|
| featured_date | date | The date this pick was published (ISO 8601). One pick is published each trading morning. |
| pattern_summary | string | A plain-English description of why this symbol was selected - the key stats and seasonal context. |
| return_pct | number | null | Daily-pick result under the published target-exit rule: the predicted gain when its target was reached, otherwise the actual closing return. Null while unjudged. The separate held_to_close_return_pct and current_return_pct fields preserve closing and open-window transparency. |
| result | string | "win", "loss", or "open". A target hit wins permanently; otherwise a profitable close wins. "open" means the pick is not yet judged. Win rate divides by judged_count, excluding pending_count. |
Seasonal chart fields
| Field | Type | Definition |
|---|---|---|
| seasonal_curve | array | The single year-averaged, normalized 0-100 seasonal index curve - one {date, index} point per calendar day. index is a relative shape (0-100), NEVER a price, and the series cannot be used to reconstruct prices. This is the typical within-year shape, not per-year paths. |
| per_year | array | On a Pattern Card's receipts: one row per lookback year as {year, return_pct, result} - the % return that year and whether it was a win or loss. No price series. |
Markets (ids 0 - 16)
Market ids are permanent resource keys. They are never renumbered. Ids 14 and 15 (Korea) were removed; the gap is intentional.
| ID | Market | ML eligible | Notes |
|---|---|---|---|
| 0 | DOW 30 STOCKS | Yes | |
| 1 | NASDAQ 100 STOCKS | Yes | |
| 2 | S&P 500 STOCKS | Yes | Free tier access |
| 3 | RUSSELL 1000 STOCKS | Yes | |
| 4 | WILSHIRE 5000 | Yes | |
| 5 | INDICES COMMON | No | |
| 6 | INDICES ALL | No | |
| 7 | FUTURES & COMMODITIES | No | |
| 8 | FOREX ALL | No | |
| 9 | FOREX LIQUID | No | |
| 10 | GOVERNMENT BONDS | No | |
| 11 | ETFs | Yes | |
| 12 | LONDON EXCHANGE | No | |
| 13 | TORONTO STOCKS | No | |
| 14 | Removed (Korea) - id reserved, never reused | ||
| 15 | Removed (Korea) - id reserved, never reused | ||
| 16 | CRYPTO CURRENCIES | No | |
No raw prices ever. The API never returns OHLCV data, last price, or price-by-date. All numeric return fields are percentages, measured from entry to exit over the holding window. This is by design and is an invariant of the API contract.