edgartools: SEC EDGAR Filings Analysis

Warnings

• gotcha The SEC requires all API users to identify themselves with a name and email. Failing to do so will result in an error when making requests.
  Fix: Call `edgar.set_identity("Your Name your.email@example.com")` once at the beginning of your script, or set the `EDGAR_IDENTITY` environment variable.
• gotcha There is an unrelated package on PyPI also named `edgar`. Installing `edgar` instead of `edgartools` will lead to `ImportError`.
  Fix: Ensure you `pip install edgartools`. If you previously installed `edgar`, run `pip uninstall edgar && pip install edgartools`.
• gotcha Prior to v5.28.5, the `to_dataframe()` method for disclosure `TextBlock` concepts could contain raw HTML markup instead of plain text, leading to uncleaned data in DataFrames.
  Fix: Upgrade to edgartools v5.28.5 or newer to ensure HTML content in `TextBlock` disclosures is automatically sanitized to plain text.
• gotcha Before v5.28.3, financial statement quarter labels for companies with non-calendar fiscal years might have been incorrect, using hardcoded calendar months instead of the company's fiscal year end month.
  Fix: Upgrade to edgartools v5.28.3 or newer to get accurate quarter labels for non-calendar fiscal year companies.
• gotcha The SEC imposes rate limits (typically 10 requests per second) on EDGAR data access. Exceeding these limits can result in your IP being temporarily blocked.
  Fix: edgartools generally handles rate limiting internally, but for large-scale operations, enable local storage, batch downloads, and process filings sequentially or with careful parallel processing.
• deprecated While `cash_flow_statement()` still works, the canonical method for retrieving cash flow statements is `cashflow_statement()` (without an underscore).
  Fix: Use `financials.cashflow_statement()` for consistency and to follow the canonical naming convention.

Install

• pip install edgartools Install latest version

Imports

• Company

  from edgar import Company

  Primary class for looking up companies and their filings.
• set_identity

  from edgar import set_identity

  Most core components are imported directly from the `edgar` top-level namespace, not `edgartools`.
• get_filings

  from edgar import get_filings

  Used for fetching a broader range of filings not necessarily tied to a single company, or when working with Form 13F-HR.

Quickstart

This quickstart demonstrates how to set your SEC identity, create a `Company` object, access basic company information, and retrieve the latest income statement and balance sheet. It highlights the structured data access that edgartools provides.

import os
from edgar import Company, set_identity

# The SEC requires all API users to identify themselves with a name and email.
# Set this once or use the EDGAR_IDENTITY environment variable.
identity = os.environ.get('EDGAR_IDENTITY', 'John Doe john.doe@example.com')
set_identity(identity)

# Get a company by its ticker symbol
company = Company("AAPL")

# Access basic company data
print(f"Company: {company.name}")
print(f"Industry: {company.industry}")

# Get the company's latest financial statements
financials = company.get_financials()
income_statement = financials.income_statement()
balance_sheet = financials.balance_sheet()
cashflow_statement = financials.cashflow_statement()

print("\nLatest Income Statement (first 5 rows):\n", income_statement.head())
print("\nLatest Balance Sheet (first 5 rows):\n", balance_sheet.head())