> For the complete documentation index, see [llms.txt](https://statalpha.gitbook.io/statalpha-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://statalpha.gitbook.io/statalpha-docs/stats/seasonality.md).

# Seasonality

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**.

***

## Concept

* 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”

***

## Parameters

| 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                            |

***

## Endpoints

| 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                                  |

***

## Example Requests

### 1. Weekday seasonality

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/seasonality/weekday?symbol=AAPL&time_window=12M"
```

### 2. Month seasonality

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/seasonality/month?symbol=AAPL&time_window=5Y"
```

### 3. Top 5 best-performing weeks

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/seasonality/top?symbol=AAPL&type=week&direction=top&sort_by=avg_return_pct&limit=5"
```

***

## Example Response (summary excerpt)

```json
{
  "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"
}
```

***

## Interpretation

| 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               |

***

## Notes

* Seasonality reveals **time-dependent performance biases** across different calendar layers.
* Results help identify **strong or weak calendar patterns** for backtesting and signal weighting.
* All users can access the same endpoints; subscription plans only affect query flexibility.
* Cached responses ensure consistent performance across repeated queries.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://statalpha.gitbook.io/statalpha-docs/stats/seasonality.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.