> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Congressional Trading Activity

> Near real-time securities transaction disclosures by U.S. Senators and House Representatives under the STOCK Act. Covers 520+ politicians, 4,700+ tickers, and 68,000+ transactions with history back to January 2014.

<Info>**Python function:** `getPoliticianTradesData()`</Info>

| Specification      | Value                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Delivery Frequency | continuous                                                                                |
| Data Frequency     | event-driven                                                                              |
| Reporting Lag      | \< 5 min from filing publication; politician filing delay typically 8–45 days after trade |
| Coverage           | 520+ politicians (Senate + House), 4,700+ tickers, STOCK Act disclosures                  |
| History            | Since 2014-01-02                                                                          |
| Availability       | Free                                                                                      |

# Product Overview

## Overview

Congressional Trading Activity provides structured, near real-time data on securities transactions disclosed by U.S. Senators and House Representatives, as mandated by the STOCK Act of 2012. The dataset unifies filings from two separate government disclosure systems into a single queryable feed.

The dataset contains **68,000+ transactions** from **520+ politicians** across **4,700+ tickers**, with history back to **January 2014**.

## Data Pipeline & Latency

Scalar Field ingests congressional disclosures through two independent, continuously running pipelines:

* **Senate (EFD):** Polls the Electronic Financial Disclosures system at `efdsearch.senate.gov` every **60 seconds**, fetching Periodic Transaction Reports (PTRs). Each new report is parsed into structured transaction rows.
* **House (Clerk):** Polls the House Clerk's Financial Disclosure portal at `disclosures-clerk.house.gov` every **5 minutes**. PTR PDFs are downloaded and parsed into structured rows. Yearly index archives are also processed for historical coverage.

New filings appear in the database within minutes of publication on the government portals.

### Politician Filing Delay (transaction date → disclosure filing, last 12 months, Senate)

How long after the actual trade do politicians file their disclosure:

| Delay      | % of filings |
| ---------- | ------------ |
| 1–7 days   | 4%           |
| 8–30 days  | 63%          |
| 31–45 days | 15%          |
| > 45 days  | 18%          |

The STOCK Act requires filing within **30 days** of the transaction (Senate) or **45 days** (House). In practice, \~67% of Senate filings arrive within 30 days, while \~18% exceed the 45-day window.

### Timestamp Semantics: `ts_recv` vs `filed_date` vs `transaction_date`

| Timestamp          | Meaning                                                                                                          | Use Case                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `ts_recv`          | When Scalar Field's pipeline first ingested the record (New York time). This is the **point-in-time** timestamp. | **Point-in-time backtesting.** Use this as your event timestamp to avoid look-ahead bias. |
| `filed_date`       | When the disclosure was filed/received by the government portal (New York time).                                 | **Regulatory analysis.** Measures compliance with STOCK Act filing deadlines.             |
| `transaction_date` | The actual date the politician executed the trade.                                                               | **Event studies.** The true economic event date — but only known after the filing lands.  |

## Coverage

* **Senate:** \~75 unique senators with PTR filings, \~1,400 unique tickers, \~16K transactions.
* **House:** \~325 unique representatives with PTR filings, \~3,600 unique tickers, \~53K transactions.
* **Combined:** 520+ politicians, 4,700+ tickers, 68,000+ transactions.
* **Asset types:** Stocks, stock options, municipal securities, corporate bonds, government securities, commodities/futures, cryptocurrency, and more.
* **Transaction filter:** Paper/scanned filings are automatically excluded from the unified feed.
* **History:** January 2014 to present, with continuous updates.

### Annual Volume (Senate + House combined)

| Year | Transactions |
| ---- | ------------ |
| 2014 | 2,213        |
| 2015 | 4,818        |
| 2016 | 4,706        |
| 2017 | 4,775        |
| 2018 | 5,475        |
| 2019 | 6,707        |
| 2020 | 8,721        |
| 2021 | 6,638        |
| 2022 | 4,545        |
| 2023 | 5,381        |
| 2024 | 3,654        |
| 2025 | 8,639        |

## Transaction Split

Across the full dataset: **51% Purchase** / **48% Sale** / **1% Exchange**.

### Asset Type Breakdown (Senate)

| Asset Type          | Count  |
| ------------------- | ------ |
| Stock               | 11,217 |
| Municipal Security  | 1,055  |
| Other               | 908    |
| Stock Option        | 545    |
| Corporate Bond      | 438    |
| Commodities/Futures | 146    |
| Non-Public Stock    | 122    |
| Cryptocurrency      | 7      |

### Asset Type Breakdown (House)

| Code | Asset Type                   | Count  |
| ---- | ---------------------------- | ------ |
| ST   | Stock                        | 34,491 |
| GS   | Government Securities        | 2,386  |
| CS   | Corporate Bond               | 1,261  |
| OT   | Other                        | 996    |
| OP   | Stock Option                 | 721    |
| HN   | Hedge Fund/Private Equity    | 165    |
| PS   | Non-Public Stock             | 146    |
| VA   | Variable Annuity             | 61     |
| OI   | Ownership Interest (Holding) | 60     |
| AB   | Asset-Backed Securities      | 57     |

# Querying the Data

## Basic Usage

```python theme={null}
from scalarlib import getPoliticianTradesData

# All congressional trades in 2024
df = getPoliticianTradesData(start='2024-01-01', end='2024-12-31')

# Filter by ticker
df = getPoliticianTradesData(tickers=['AAPL', 'MSFT'], start='2024-01-01', end='2024-12-31')

# Filter by politician name
df = getPoliticianTradesData(start='2024-01-01', end='2024-12-31', politician_name='pelosi')

# Filter by transaction date instead of filed date
df = getPoliticianTradesData(start='2024-01-01', end='2024-12-31', date_column='transaction_date')
```

## Parameters

| Parameter         | Type               | Required | Description                                         |
| ----------------- | ------------------ | -------- | --------------------------------------------------- |
| `tickers`         | str, list, or None | No       | Stock ticker(s). `None` returns all tickers.        |
| `start`           | str                | Yes      | Start date (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`). |
| `end`             | str                | Yes      | End date (same format; date-only is inclusive).     |
| `politician_name` | str                | No       | Politician name.                                    |
| `date_column`     | str                | No       | `'filed_date'` (default) or `'transaction_date'`.   |

# Column Definitions

## Congressional Trades Schema

| Column                          | Type     | Description                                                                                                                     |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `ts_recv`                       | datetime | **Point-in-time timestamp:** when Scalar Field ingested the record (New York time).                                             |
| `filed_date`                    | datetime | When the disclosure was filed with the government portal (New York time).                                                       |
| `full_name`                     | string   | Politician's name (format: `Last, First`).                                                                                      |
| `filer_type`                    | string   | Role: `Senator`, `Representative`, `Former Representative`.                                                                     |
| `chamber`                       | string   | `Senate` or `House`.                                                                                                            |
| `side`                          | string   | Transaction direction: `Purchase`, `Sale (Full)`, `Sale (Partial)`, `Exchange`.                                                 |
| `ticker`                        | string   | Ticker symbol of the security (may be null for non-equity assets).                                                              |
| `asset_name`                    | string   | Full name/description of the asset.                                                                                             |
| `asset_type`                    | string   | Security type: `Stock`, `Stock Option`, `Corporate Bond`, `Municipal Security`, `Government Securities`, `Cryptocurrency`, etc. |
| `owner`                         | string   | Ownership: `Self`, `Spouse`, `Joint`, `Dependent Child`.                                                                        |
| `transaction_date`              | date     | Calendar date the trade was executed.                                                                                           |
| `transaction_value_lower_range` | float    | Lower bound of the reported transaction amount range (USD).                                                                     |
| `transaction_value_upper_range` | float    | Upper bound of the reported transaction amount range (USD).                                                                     |
| `description`                   | string   | Additional detail (e.g., option strike/expiry, bond coupon).                                                                    |
| `uid_link`                      | string   | Link to the original filing on the government portal.                                                                           |

## Amount Ranges

Congressional disclosures report transaction values in ranges rather than exact amounts:

| Range                     |
| ------------------------- |
| $1,001 – $15,000          |
| $15,001 – $50,000         |
| $50,001 – $100,000        |
| $100,001 – $250,000       |
| $250,001 – $500,000       |
| $500,001 – $1,000,000     |
| $1,000,001 – $5,000,000   |
| $5,000,001 – $25,000,000  |
| $25,000,001 – $50,000,000 |
| Over \$50,000,000         |