stocks-earnings-dates 0.1.9

Access 22 years of historical earnings dates for S&P 500 and Nasdaq stocks.

📈 stocks-earnings-dates

A lightweight Python package to query historical earnings release dates for all stocks in the S&P 500 and the top 100 Nasdaq.
It provides access to the last 21 years of earnings dates, since the earnings was released as the Item 2.02 in the 8-K Reports (the number of earnings for stock is fewer if the company is more recently listed).

---

Installation

Install the package via pip:

pip install stocks-earnings-dates --upgrade

---

Project structure

stocks-earnings-dates/
├─ build/
├─ dist/
├─ edgar_earnings_pipeline/
│  ├─ 8k-link-builder/
│  │  ├─ EDGAR_8K_LINKS_GENERATOR.py
│  │  └─ edgar_8k_links_only.csv
│  ├─ earnings_item_2_02_scrapper/
│  │  └─ scrapping_script.py
│  ├─ ticker_cik_mapping/
│  │  ├─ CIK_GENERATOR.py
│  │  └─ tickers_with_cik.csv
│  └─ earnings_final.csv
├─ stocks_earnings_dates/
│  ├─ data/
│  │  └─ earnings.db
│  ├─ __init__.py
│  └─ core.py
├─ stocks_earnings_dates.egg-info/
├─ earnings_final.csv
└─ generate_db.py

---

What’s Inside?

This package uses a built-in SQLite database with over 37,000+ earnings dates collected from the public sources of SEC EDGAR

You can easily:

• Get all historical earnings dates for a given stock.
• List all supported tickers.
• Analyze price movement (%) after each earnings date:
  • Close → Open
  • Close → Close
  • Open → Close

---

Usage

🔍 Get earnings dates only:

from stocks_earnings_dates import get_earnings, list_all_tickers

# Get earnings dates for a specific ticker
dates = get_earnings("AAPL")
print(dates)
# Output: ['2024-08-01', '2024-05-02', ..., '2014-07-22']

# List all tickers available in the database
tickers = list_all_tickers()
print(tickers)

---

Get price reactions for each earnings date:

from stocks_earnings_dates import get_earnings_price_reactions

reactions = get_earnings_price_reactions("AAPL")
for r in reactions:
    print(
        f"Earnings Date: {r['date']}, "
        f"Close→Open: {r['close_to_open_pct']}%, "
        f"Close→Close: {r['close_to_close_pct']}%, "
        f"Open→Close: {r['open_to_close_pct']}%"
    )

Output example:

Earnings Date: 2024-04-25, Close→Open: +2.45%, Close→Close: +4.38%, Open→Close: +1.88%
Earnings Date: 2024-01-19, Close→Open: -0.89%, Close→Close: -1.25%, Open→Close: -0.36%

These values are automatically calculated using yfinance.

---

Rebuild the DB

python generate_db.py

How It Works

The earnings dates are stored locally in a bundled SQLite database. When using the price reaction function, the package:

• Loads the dates from the local database
• Fetches the daily stock price data surrounding those earnings dates from Yahoo Finance.
• Calculates the percentage change from:
  • Previous Close → Next Open
  • Previous Close → Next Close
  • Next Open → Next Close -“Previous Close” refers to the stock’s closing price just before the earnings release (typically after hours). “Next Open” is the price at market open the following day, and “Next Close” is the closing price on that same day.

---

⚙️ Why SQLite?

This package uses SQLite internally to optimize both speed and memory usage when querying earnings dates.

Instead of loading the entire .csv file into memory every time, only the subset of data requested (such as the earnings dates for a single ticker) is loaded when needed.
This improves the efficiency when accessing multiple tickers.

---

Pipeline of Data extraction

How the scrapping links are created:

For each stock in the tickers_with_cik.csv, the edgar_8k_links_generator creates 4 links for each stock's CIK

How Earnings Dates Are Detected:

The scrapping code looks for SEC 8-K filings that report quarterly results (Item 2.02).

For older filings (before Aug 23 2004), it also includes Item 12, the previous code for earnings releases.

If more than one earnings-related 8-K is filed for the same quarter (e.g., corrections or updates), only the first filing within a 60-day window is kept to avoid duplicates. The earnings database was compiled from publicly accessible financial websites.
The CSV was cleaned, normalized and converted to a bundled SQLite database.

Limitations

• This is a static dataset. Updates are not (yet) automated.
• EPS data and surprise values are not included (yet).

---

Future Plans

• Add EPS (expected vs actual) and calculate surprise %
• Automatically update the database each quarter scrapping EDGAR

Fair use

• Set a real User‑Agent with contact email.
• Sleep between requests; do not hammer SEC EDGAR.
• Not affiliated with the SEC.

---

👨‍💻 Author

Made by Albert Pérez
GitHub: AlbertPerez7

---