For any developer building a financial application, the ability to programmatically detect and react to corporate events is a significant advantage. Form 8-K filings are the SEC's mechanism for reporting unscheduled, material events—information that can directly impact a company's stock price and market sentiment. Manually tracking these filings is impossible at scale, which is why automating the process is so valuable.
By fetching and parsing 8-K data, your application can:
- Generate Trading Signals: Events like the announcement of a merger (Item 1.01), unexpected executive departures (Item 5.02), or bankruptcy proceedings (Item 1.03) can serve as powerful inputs for algorithmic trading strategies.
- Improve Risk Management: Automatically flag companies in a portfolio that report events related to financial obligations or non-reliance on previously issued financial statements (Item 4.02).
- Create Smarter News Feeds: Build a real-time news feed that goes beyond headlines, providing users with alerts based on the specific substance of an SEC filing.
- Conduct Quantitative Analysis: Aggregate event data over time to find correlations between certain types of events and future stock performance.
This guide walks you through building such a system using Python and the FinFeedAPI. You will see how to fetch 8-K filings, filter them for a specific event type, examine how often that event occurs, and then pull the exact text describing it.
This guide covers:
- Fetching 8-K filings that report a specific event.
- Analyzing the frequency of that event over time.
- Extracting the detailed text associated with the event.
What you need:
- Python 3.x with pandas and matplotlib.
- The api-bricks-sec-api-rest library.
- Your FinFeedAPI key.
1. Environment Setup
First, you need to install the FinFeedAPI client library.
pip install api-bricks-sec-api-rest
Next, prepare your Python script. This includes importing the required libraries and configuring the API client with your key. For this example, we will track Item 5.02, which relates to the departure or appointment of directors and certain officers.
# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
from datetime import datetime
import api_bricks_sec_api_rest
# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)
# --- Analysis Parameters ---
# Define the event item number to track
TARGET_EVENT_ITEM = "5.02" # Example: Track executive/director changes
# Define time range (e.g., look back one year)
end_date = datetime.now().strftime('%Y-%m-%d')
start_date = (datetime.now() - pd.DateOffset(years=1)).strftime('%Y-%m-%d')
# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (14, 7)
- Fetching 8-K Filings for a Specific Event
The most direct way to find filings related to a specific event is to use the
items_containparameter in the/v1/filingsendpoint. This allows you to filter for 8-Ks that list your target item number.
The following code fetches all 8-K filings from the last year that contain Item 5.02.
# Initialize the FilingMetadataApi
filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)
print(f"Fetching 8-K filings containing Item '{TARGET_EVENT_ITEM}'...")
event_filings = []
current_page = 1
page_size = 200
while True:
try:
page_data = filing_metadata_api.v1_filings_get(
form_type="8-K",
filling_date_start=start_date,
filling_date_end=end_date,
items_contain=TARGET_EVENT_ITEM, # Direct filter
page_size=page_size,
page_number=current_page
)
if page_data:
event_filings.extend(page_data)
print(f" Fetched page {current_page}, {len(page_data)} records. Total: {len(event_filings)}")
if len(page_data) < page_size:
print(" Last page reached.")
break
current_page += 1
else:
print(f" No more data found.")
break
except api_bricks_sec_api_rest.ApiException as e:
print(f"API Exception occurred: {e}")
break
# Process results into a DataFrame
if event_filings:
event_filings_df = pd.DataFrame.from_records([vars(f) for f in event_filings])
event_filings_df['filing_date'] = pd.to_datetime(event_filings_df['filing_date'], errors='coerce')
print(f"\nFound {len(event_filings_df)} filings containing Item {TARGET_EVENT_ITEM}.")
else:
print(f"\nNo filings found for Item {TARGET_EVENT_ITEM}.")
event_filings_df = pd.DataFrame()
An alternative, more thorough method is to fetch all 8-K filings in a period and then use the /v1/extractor endpoint on each one to check its items. This requires more API calls but can be more reliable if the items_contain filter is not specific enough for your needs. For the rest of this guide, we will use the results from the direct filtering method above.
3. Analyze Event Frequency
With a list of relevant filings, you can analyze how often this event occurs. A bar chart showing the number of event filings per month is a good way to visualize this.
if not event_filings_df.empty:
event_filings_df = event_filings_df.dropna(subset=['filing_date'])
if not event_filings_df.empty:
# Resample by month and count the number of filings
events_by_month = event_filings_df.set_index('filing_date').resample('ME').size()
# Create the plot
plt.figure(figsize=(14, 7))
events_by_month.plot(kind='bar', color='purple', edgecolor='black')
plt.title(f'Frequency of 8-K Filings with Item {TARGET_EVENT_ITEM} (Monthly)')
plt.xlabel('Month')
plt.ylabel('Number of Filings')
plt.xticks(rotation=45, ha='right')
plt.grid(True, axis='y', linestyle='--', alpha=0.7)
plt.tight_layout()
plt.show()
else:
print("No event filings data available to analyze frequency.")
This code groups the filings by month and plots the count, giving you a clear view of when the target event was most frequently reported.
4. Extract Specific Event Details
The final step is to get the actual text describing the event. Using the accession_number from one of the filings you found, you can call the /v1/extractor/item endpoint to get the content for just that item.
if not event_filings_df.empty:
# Select the most recent event filing
event_to_extract = event_filings_df.sort_values('filing_date', ascending=False).iloc[0]
acc_no = event_to_extract['accession_number']
print(f"\nExtracting details for Item '{TARGET_EVENT_ITEM}' from filing: {acc_no}")
# Initialize the ContentExtractionApi
content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)
try:
event_content = content_extraction_api.v1_extractor_item_get(
accession_number=acc_no,
item_number=TARGET_EVENT_ITEM
)
if event_content:
print(f"\nContent for Item {TARGET_EVENT_ITEM} (first 1000 chars):\n")
print(event_content[:1000] + "...")
except api_bricks_sec_api_rest.ApiException as e:
print(f"API Exception when extracting item: {e}")
else:
print("\nNo filings identified to extract details from.")
This code selects the latest filing from our list and retrieves the specific text related to Item 5.02, giving you the direct information about the officer change.
Final Thoughts
This guide showed how to use the FinFeedAPI to build a workflow for detecting and analyzing specific corporate events from 8-K filings. By filtering for item numbers, you can turn unstructured regulatory documents into a structured feed of events. This method can be adapted to track any of the various 8-K item types, providing timely information for your financial applications.
Top comments (1)
Just a heads up that you can add highlighting to the code blocks if you'd like. Just change:
... to specify the language:
More details in our editor guide!