Files

kdusek 8e654ed209 Initial commit

2025-12-09 12:13:01 +01:00

24 KiB

Raw Blame History

Company Class Documentation

Overview

The Company class represents a public company that files with the SEC. It provides comprehensive access to company information, filings, financial data, and metadata. Company extends the Entity class with company-specific functionality like financial statements, ticker lookup, and enhanced data access.

Key Features:

Access all company filings via SEC submissions API
Retrieve structured financial data (facts)
Get financial statements from 10-K and 10-Q filings
Access company metadata (tickers, exchanges, addresses, industry)
Simplified interface for common company analysis workflows

Common Actions

Quick reference for the most frequently used Company methods:

Get a Company

# By ticker (case-insensitive)
company = Company("AAPL")
company = Company("aapl")  # Works the same

# By CIK (Central Index Key)
company = Company(320193)           # Integer
company = Company("320193")         # String (no padding)
company = Company("0000320193")     # String (zero-padded)

Access Filings

# Get all filings
filings = company.get_filings()

# Filter by form type
filings_10k = company.get_filings(form="10-K")
filings_8k = company.get_filings(form="8-K")
filings_multi = company.get_filings(form=["10-K", "10-Q"])

# Get latest filing
latest = company.get_filings(form="10-K").latest()

# Quick access to latest reports
latest_10k = company.latest_tenk  # Latest 10-K as TenK object
latest_10q = company.latest_tenq  # Latest 10-Q as TenQ object

Access Financial Data

# Get company facts (from SEC Company Facts API)
facts = company.get_facts()

# Access facts property (cached)
facts = company.facts

# Get financial statements from latest filings
financials = company.get_financials()           # From latest 10-K
quarterly = company.get_quarterly_financials()  # From latest 10-Q

Getting a Company

By Ticker Symbol

The most common way to get a company is by ticker symbol:

from edgar import Company

# Ticker is case-insensitive
apple = Company("AAPL")
tesla = Company("TSLA")
microsoft = Company("msft")  # Lowercase works too

How it works: EdgarTools looks up the ticker in SEC reference data to find the CIK, then loads company data using that CIK.

Note: Some companies have multiple tickers. The ticker lookup finds the company (CIK) that the ticker belongs to.

By CIK (Central Index Key)

For direct access, use the CIK:

# CIK as integer (preferred)
apple = Company(320193)

# CIK as string (no padding needed)
apple = Company("320193")

# CIK as zero-padded string (also works)
apple = Company("0000320193")

Why use CIK?

Faster (one API call vs. two for ticker lookup)
Unique identifier (never changes)
Avoids ticker ambiguity

Company Not Found

from edgar import Company

try:
    company = Company("INVALID")
except Exception as e:
    print(f"Company not found: {e}")

# Or check after creation
company = Company("AAPL")
if company.not_found:
    print("Company not found")

Core Properties

Identity Properties

Property	Type	Description
`name`	str	Official company name
`cik`	int	Central Index Key (unique identifier)
`tickers`	List[str]	All ticker symbols for the company
`fiscal_year_end`	str	Fiscal year end date (e.g., "12-31")

Classification Properties

Property	Type	Description
`sic`	int	Standard Industrial Classification code
`industry`	str	Industry description from SIC
`is_company`	bool	True if entity is a company (vs. individual)
`is_individual`	bool	True if entity is an individual

Financial Data Properties

Property	Type	Description
`facts`	EntityFacts	Company facts from SEC API (cached)
`latest_tenk`	TenK	Latest 10-K filing object
`latest_tenq`	TenQ	Latest 10-Q filing object
`public_float`	float	Public float value (if available)
`shares_outstanding`	int	Outstanding shares (if available)

Status Properties

Property	Type	Description
`not_found`	bool	True if company was not found

Core Methods

get_filings()

Get company filings with optional filtering:

def get_filings(
    form: str | List[str] = None,
    accession_number: str | List[str] = None,
    file_number: str | List[str] = None,
    is_xbrl: bool = None,
    is_inline_xbrl: bool = None,
    sort_by: str = "filing_date"
) -> EntityFilings

Parameters:

form: Form type(s) to filter (e.g., "10-K", ["10-K", "10-Q"])
accession_number: Specific accession number(s)
file_number: SEC file number(s) for tracking related filings
is_xbrl: Filter for XBRL filings only
is_inline_xbrl: Filter for inline XBRL filings only
sort_by: Sort order (default: "filing_date")

Returns: EntityFilings collection

Examples:

# Get all filings
all_filings = company.get_filings()

# Get specific form type
filings_10k = company.get_filings(form="10-K")
filings_10q = company.get_filings(form="10-Q")

# Multiple form types
annual_quarterly = company.get_filings(form=["10-K", "10-Q"])

# Filter by XBRL availability
xbrl_filings = company.get_filings(is_xbrl=True)
inline_xbrl = company.get_filings(is_inline_xbrl=True)

# Get specific filing by accession number
specific = company.get_filings(
    accession_number="0000320193-24-000123"
)

# Get related filings by file number
related = company.get_filings(file_number="001-36743")

get_facts()

Get structured financial data from SEC Company Facts API:

def get_facts() -> EntityFacts

Returns: EntityFacts object containing company financial data

Examples:

# Get facts
facts = company.get_facts()

# Access via property (cached)
facts = company.facts

# Work with facts
income_stmt = facts.get_income_statement()
balance_sheet = facts.get_balance_sheet()
cash_flow = facts.get_cash_flow_statement()

Note: Facts are cached after first access. The .facts property provides convenient cached access.

get_financials()

Get financial statements from latest 10-K:

def get_financials() -> Optional[Financials]

Returns: Financials object from latest 10-K, or None if not available

Examples:

# Get annual financials
financials = company.get_financials()

if financials:
    print(financials.income_statement)
    print(financials.balance_sheet)
    print(financials.cash_flow)

get_quarterly_financials()

Get financial statements from latest 10-Q:

def get_quarterly_financials() -> Optional[Financials]

Returns: Financials object from latest 10-Q, or None if not available

Examples:

# Get quarterly financials
quarterly = company.get_quarterly_financials()

if quarterly:
    print(quarterly.income_statement)

get_ticker()

Get the primary ticker symbol:

def get_ticker() -> Optional[str]

Returns: Primary ticker symbol, or None if no tickers

Examples:

ticker = company.get_ticker()
if ticker:
    print(f"Trading as: {ticker}")

get_exchanges()

Get all exchanges where company is listed:

def get_exchanges() -> List[str]

Returns: List of exchange names

Examples:

exchanges = company.get_exchanges()
for exchange in exchanges:
    print(f"Listed on: {exchange}")

Accessing Filings

Get All Filings

company = Company("AAPL")

# Get all filings (returns EntityFilings)
filings = company.get_filings()

print(f"Total filings: {len(filings)}")

# Iterate through filings
for filing in filings:
    print(f"{filing.form}: {filing.filing_date}")

Filter by Form Type

# Single form type
filings_10k = company.get_filings(form="10-K")
filings_8k = company.get_filings(form="8-K")
filings_def14a = company.get_filings(form="DEF 14A")

# Multiple form types
annual_reports = company.get_filings(form=["10-K", "10-K/A"])
periodic = company.get_filings(form=["10-K", "10-Q"])

Get Latest Filing

# Get latest 10-K
latest_10k = company.get_filings(form="10-K").latest()

# Get latest 8-K
latest_8k = company.get_filings(form="8-K").latest()

# Get multiple latest filings
latest_5_10ks = company.get_filings(form="10-K").latest(5)

Quick Access to Latest Reports

# Property access to latest reports (as form-specific objects)
latest_10k = company.latest_tenk  # Returns TenK object
latest_10q = company.latest_tenq  # Returns TenQ object

# Access financial statements directly
if latest_10k:
    print(latest_10k.financials.income_statement)

Filter by XBRL

# Get only XBRL filings
xbrl_filings = company.get_filings(is_xbrl=True)

# Get only inline XBRL filings
inline_xbrl = company.get_filings(is_inline_xbrl=True)

# Check specific form for XBRL
xbrl_10ks = company.get_filings(form="10-K", is_xbrl=True)

Working with Filing Results

# Get filings
filings = company.get_filings(form="10-K")

# Access by index
first_filing = filings[0]
tenth_filing = filings[9]

# Convert to DataFrame
df = filings.to_pandas()

# Get subset
recent_10 = filings.head(10)
last_10 = filings.tail(10)

# Filter further
filings_2024 = filings.filter(filing_date="2024-01-01:")

Accessing Financial Data

Company Facts API

The SEC provides structured financial data via the Company Facts API:

company = Company("AAPL")

# Get facts
facts = company.get_facts()

# Or use cached property
facts = company.facts

# Build financial statements from facts
income = facts.get_income_statement()
balance = facts.get_balance_sheet()
cashflow = facts.get_cash_flow_statement()

Financial Statements from Filings

Get financials directly from 10-K or 10-Q filings:

# From latest 10-K
annual_financials = company.get_financials()

if annual_financials:
    income = annual_financials.income_statement
    balance = annual_financials.balance_sheet
    cashflow = annual_financials.cash_flow

# From latest 10-Q
quarterly_financials = company.get_quarterly_financials()

if quarterly_financials:
    income = quarterly_financials.income_statement

XBRL from Filings

Access raw XBRL data:

# Get latest 10-K filing
filing = company.get_filings(form="10-K").latest()

# Parse XBRL
xbrl = filing.xbrl()

# Access statements
income = xbrl.statements.income_statement()
balance = xbrl.statements.balance_sheet()

# Convert to DataFrame
df = income.to_dataframe()

Company Metadata

Identity and Contact

company = Company("AAPL")

# Basic identity
print(f"Name: {company.name}")
print(f"CIK: {company.cik}")

# Access detailed data
data = company.data

# Addresses
if data.business_address:
    print(f"Business Address: {data.business_address}")
if data.mailing_address:
    print(f"Mailing Address: {data.mailing_address}")

# Contact information
if hasattr(data, 'phone'):
    print(f"Phone: {data.phone}")
if hasattr(data, 'website'):
    print(f"Website: {data.website}")

Tickers and Exchanges

# Get all tickers
tickers = company.tickers
print(f"Tickers: {', '.join(tickers)}")

# Get primary ticker
primary = company.get_ticker()
print(f"Primary ticker: {primary}")

# Get exchanges
exchanges = company.get_exchanges()
for exchange in exchanges:
    print(f"Listed on: {exchange}")

Industry Classification

# SIC code and description
print(f"SIC: {company.sic}")
print(f"Industry: {company.industry}")

# Fiscal year end
print(f"Fiscal Year End: {company.fiscal_year_end}")

# Entity type and category
data = company.data
if hasattr(data, 'entity_type'):
    print(f"Entity Type: {data.entity_type}")
if hasattr(data, 'category'):
    print(f"Category: {data.category}")

Former Names

data = company.data

if hasattr(data, 'former_names') and data.former_names:
    print("Former Names:")
    for former in data.former_names:
        print(f"  {former['name']}: {former['from']} to {former['to']}")

Common Workflows

Analyze Annual Reports Over Time

company = Company("AAPL")

# Get all 10-K filings
filings_10k = company.get_filings(form="10-K")

# Get last 5 years
last_5_years = filings_10k.latest(5)

# Analyze each year
for filing in last_5_years:
    print(f"\n{filing.filing_date} - {filing.report_date}")

    # Get XBRL data
    xbrl = filing.xbrl()

    # Get income statement
    income = xbrl.statements.income_statement()
    df = income.to_dataframe()

    # Show revenue
    if 'Revenue' in df.index:
        revenue = df.loc['Revenue'].iloc[0]
        print(f"  Revenue: ${revenue:,.0f}")

Track Quarterly Performance

company = Company("AAPL")

# Get all 10-Q filings
filings_10q = company.get_filings(form="10-Q")

# Get last 4 quarters
last_4_quarters = filings_10q.latest(4)

# Analyze each quarter
quarterly_revenue = []

for filing in last_4_quarters:
    xbrl = filing.xbrl()

    # Get revenue from current period
    current = xbrl.current_period
    income = current.income_statement()

    # Extract revenue
    df = income.to_dataframe()
    if 'Revenue' in df.index:
        revenue = df.loc['Revenue'].iloc[0]
        quarterly_revenue.append({
            'period': filing.report_date,
            'revenue': revenue
        })

# Show trend
import pandas as pd
trend_df = pd.DataFrame(quarterly_revenue)
print(trend_df)

Compare Multiple Companies

companies = {
    'AAPL': Company("AAPL"),
    'MSFT': Company("MSFT"),
    'GOOGL': Company("GOOGL")
}

results = []

for ticker, company in companies.items():
    # Get latest 10-K
    filing = company.get_filings(form="10-K").latest()

    if filing and filing.is_xbrl:
        xbrl = filing.xbrl()
        income = xbrl.statements.income_statement()
        df = income.to_dataframe()

        # Extract key metrics
        results.append({
            'ticker': ticker,
            'company': company.name,
            'revenue': df.loc['Revenue'].iloc[0] if 'Revenue' in df.index else None,
            'net_income': df.loc['Net Income'].iloc[0] if 'Net Income' in df.index else None
        })

# Compare
import pandas as pd
comparison_df = pd.DataFrame(results)
print(comparison_df)

Find Earnings Announcements

company = Company("AAPL")

# Get 8-K filings
filings_8k = company.get_filings(form="8-K")

# Find earnings announcements (Item 2.02)
earnings_8ks = []

for filing in filings_8k:
    if filing.items and "2.02" in filing.items:
        earnings_8ks.append({
            'filing_date': filing.filing_date,
            'report_date': filing.report_date,
            'items': filing.items
        })

# Show recent earnings dates
import pandas as pd
earnings_df = pd.DataFrame(earnings_8ks).head(10)
print(earnings_df)

Export Company Data

company = Company("AAPL")

# Get all filings
filings = company.get_filings(form=["10-K", "10-Q"])

# Convert to DataFrame
df = filings.to_pandas()

# Export to CSV
df.to_csv("apple_filings.csv", index=False)

# Export facts
facts = company.get_facts()
facts_df = facts.to_pandas()
facts_df.to_csv("apple_facts.csv")

# Export specific statement
income = facts.get_income_statement()
income.to_csv("apple_income.csv")

Build Custom Dashboard

company = Company("AAPL")

# Collect key metrics
dashboard = {
    'company': company.name,
    'ticker': company.get_ticker(),
    'cik': company.cik,
    'industry': company.industry,
    'fiscal_year_end': company.fiscal_year_end
}

# Add latest filing info
latest_10k = company.get_filings(form="10-K").latest()
if latest_10k:
    dashboard['latest_10k_date'] = latest_10k.filing_date
    dashboard['latest_10k_period'] = latest_10k.report_date

latest_10q = company.get_filings(form="10-Q").latest()
if latest_10q:
    dashboard['latest_10q_date'] = latest_10q.filing_date
    dashboard['latest_10q_period'] = latest_10q.report_date

# Add financial metrics
try:
    facts = company.get_facts()
    income = facts.get_income_statement(annual=True, periods=1)

    # Extract metrics (adjust based on your needs)
    dashboard['latest_revenue'] = "See income statement"
    dashboard['latest_net_income'] = "See income statement"
except:
    dashboard['facts_available'] = False

print(dashboard)

Best Practices

1. Use Ticker for Convenience, CIK for Performance

# Good for interactive use
company = Company("AAPL")

# Better for production/scripts
company = Company(320193)

2. Cache the Company Object

# Good - reuse company object
company = Company("AAPL")
filings_10k = company.get_filings(form="10-K")
filings_10q = company.get_filings(form="10-Q")
facts = company.facts

# Less efficient - creates company multiple times
filings_10k = Company("AAPL").get_filings(form="10-K")
filings_10q = Company("AAPL").get_filings(form="10-Q")

3. Use Latest Properties for Quick Access

# Good - uses cached property
latest_10k = company.latest_tenk

# More verbose
latest_10k = company.get_filings(form="10-K").latest().obj()

4. Check XBRL Availability

filing = company.get_filings(form="10-K").latest()

if filing.is_xbrl:
    xbrl = filing.xbrl()
    # Process XBRL data
else:
    # Fall back to text parsing or skip
    print("No XBRL data available")

5. Handle Missing Data Gracefully

company = Company("AAPL")

# Check if facts are available
try:
    facts = company.get_facts()
    income = facts.get_income_statement()
except Exception as e:
    print(f"Facts not available: {e}")
    income = None

# Check if filings exist
filings = company.get_filings(form="10-K")
if not filings.empty:
    latest = filings.latest()
else:
    print("No 10-K filings found")

Error Handling

Company Not Found

from edgar import Company

try:
    company = Company("INVALIDTICKER")
except Exception as e:
    print(f"Error: {e}")

# Or check after creation
company = Company("AAPL")
if company.not_found:
    print("Company not found")
    exit()

No Filings Available

filings = company.get_filings(form="RARE-FORM")

if filings.empty:
    print("No filings of this type found")
else:
    latest = filings.latest()

Facts Not Available

try:
    facts = company.get_facts()
except Exception as e:
    print(f"Facts not available: {e}")
    facts = None

# Some companies may not have facts data
if facts is None:
    print("Using alternative data source")

Missing Financial Statements

financials = company.get_financials()

if financials is None:
    print("No 10-K with financials found")
    # Try quarterly
    financials = company.get_quarterly_financials()

if financials:
    # Process financials
    pass

Performance Considerations

Minimize API Calls

# Good - one company object, reused
company = Company("AAPL")
filings = company.get_filings()
facts = company.facts
latest_10k = company.latest_tenk

# Less efficient - creates company 3 times
filings = Company("AAPL").get_filings()
facts = Company("AAPL").facts
latest_10k = Company("AAPL").latest_tenk

Use Facts Property (Cached)

# First call fetches data
facts = company.facts

# Subsequent calls use cache
income = company.facts.get_income_statement()
balance = company.facts.get_balance_sheet()

Filter Filings Early

# Good - filter at source
recent_10ks = company.get_filings(form="10-K", is_xbrl=True)

# Less efficient - get all then filter
all_filings = company.get_filings()
recent_10ks = [f for f in all_filings if f.form == "10-K" and f.is_xbrl]

Use EntityFilings Methods

filings = company.get_filings(form="10-K")

# Good - use built-in methods
latest = filings.latest()
recent_5 = filings.latest(5)

# Less efficient - manual slicing
sorted_filings = sorted(filings, key=lambda f: f.filing_date, reverse=True)
latest = sorted_filings[0]

Display and Representation

Rich Display

Company has a rich display showing comprehensive information:

company = Company("AAPL")
print(company)

Shows:

Company name and ticker
CIK and entity type
Category and industry (SIC)
Fiscal year end
Trading exchanges and symbols
Business and mailing addresses
Contact information
Former names (if any)

String Representation

# Simple string representation
str(company)  # Returns "Company(name='Apple Inc.', cik=320193)"

# Display in console
print(company)  # Shows rich formatted display

Integration with Other Classes

Company → EntityFilings → EntityFiling

company = Company("AAPL")           # Company object

filings = company.get_filings()     # EntityFilings collection
# Type: EntityFilings (maintains company context)

filing = filings[0]                 # EntityFiling instance
# Type: EntityFiling (has entity-specific metadata)

# EntityFiling knows its company
entity = filing.get_entity()        # Returns the Company

Company → Facts → Statements

company = Company("AAPL")

facts = company.get_facts()         # EntityFacts object

income = facts.get_income_statement()    # Statement object
balance = facts.get_balance_sheet()      # Statement object

Company → Filing → XBRL

company = Company("AAPL")

filing = company.get_filings(form="10-K").latest()

xbrl = filing.xbrl()                # XBRL object

statements = xbrl.statements        # Statements collection
income = statements.income_statement()

Comparison: Company vs Entity

Company extends Entity with company-specific features:

Feature	Entity	Company
Basic identity (name, CIK)	✅	✅ (inherited)
Get filings	✅	✅ (inherited)
Tickers	✅	✅ (enhanced)
Facts	❌	✅
Financial statements	❌	✅
latest_tenk / latest_tenq	❌	✅
get_financials()	❌	✅
get_quarterly_financials()	❌	✅

When to use Company: 95% of use cases (public companies) When to use Entity: Individual filers or when entity type is unknown

Troubleshooting

"Company not found"

Cause: Ticker or CIK doesn't exist or is misspelled

Solution:

# Verify ticker
from edgar import find_company

results = find_company("APPL")  # Search for similar
for result in results:
    print(f"{result.name}: {result.ticker}")

"No filings found"

Cause: Company may be newly registered or form type is wrong

Solution:

# Check what filings exist
all_filings = company.get_filings()
print(f"Total filings: {len(all_filings)}")

# Check form types
df = all_filings.to_pandas()
print(df['form'].value_counts())

"Facts not available"

Cause: Company may be investment company, foreign filer, or recently registered

Solution:

# Check entity type
print(f"Entity type: {company.data.entity_type}")

# Fall back to XBRL from filings
filing = company.get_filings(form="10-K").latest()
if filing and filing.is_xbrl:
    xbrl = filing.xbrl()
    # Use XBRL instead of facts

"Ticker has multiple companies"

Cause: Some tickers may have had multiple owners over time

Solution:

# Use CIK for specific company
company = Company(320193)  # Specific to Apple Inc.

# Or verify after ticker lookup
company = Company("AAPL")
print(f"Got: {company.name} (CIK: {company.cik})")

This comprehensive guide covers everything you need to work with Company objects in edgartools, from basic usage to advanced workflows and integration patterns.

24 KiB Raw Blame History

Company Class Documentation

Overview

Common Actions

Get a Company

Access Filings

Access Financial Data

Company Information

Getting a Company

By Ticker Symbol

By CIK (Central Index Key)

Company Not Found

Core Properties

Identity Properties

Classification Properties

Financial Data Properties

Status Properties

Core Methods

get_filings()

get_facts()

get_financials()

get_quarterly_financials()

get_ticker()

get_exchanges()

Accessing Filings

Get All Filings

Filter by Form Type

Get Latest Filing

Quick Access to Latest Reports

Filter by XBRL

Working with Filing Results

Accessing Financial Data

Company Facts API

Financial Statements from Filings

XBRL from Filings

Company Metadata

Identity and Contact

Tickers and Exchanges

Industry Classification

Former Names

Common Workflows

Analyze Annual Reports Over Time

Track Quarterly Performance

Compare Multiple Companies

Find Earnings Announcements

Export Company Data

Build Custom Dashboard

Best Practices

1. Use Ticker for Convenience, CIK for Performance

2. Cache the Company Object

3. Use Latest Properties for Quick Access

4. Check XBRL Availability

5. Handle Missing Data Gracefully

Error Handling

Company Not Found

No Filings Available

Facts Not Available

Missing Financial Statements

Performance Considerations

Minimize API Calls

Use Facts Property (Cached)

Filter Filings Early

Use EntityFilings Methods

Display and Representation

Rich Display

String Representation

Integration with Other Classes

Company → EntityFilings → EntityFiling

Company → Facts → Statements

Company → Filing → XBRL

Comparison: Company vs Entity

Troubleshooting

"Company not found"

"No filings found"

"Facts not available"

"Ticker has multiple companies"

24 KiB

Raw Blame History