Skip to content

Latest commit

 

History

History
233 lines (164 loc) · 6.79 KB

README.md

File metadata and controls

233 lines (164 loc) · 6.79 KB

SEC EDGAR Python Client

Query institutional holdings, SEC filings, and 10,000+ public companies

Python 3.10+ License: MIT RapidAPI

A clean, Pythonic wrapper around the SEC EDGAR Financial Data API on RapidAPI. Get institutional 13F portfolio holdings, search 10,000+ public companies, and explore SEC filings — all with a single pip install.

Get Your Free API Key

Subscribe on RapidAPI — free tier available, no credit card required.

Install

pip install edgar-client

Quick Start

from edgar_client import EdgarAPI

with EdgarAPI(api_key="YOUR_RAPIDAPI_KEY") as api:
    portfolio = api.holdings(EdgarAPI.BERKSHIRE)

    print(f"{portfolio.company_name}  —  {portfolio.report_date}")
    print(f"Total AUM: ${portfolio.total_value_billions:.1f}B\n")

    for h in portfolio.top(5):
        print(f"  {h.name_of_issuer:<35}  ${h.value_millions:>10,.1f}M")

Output:

BERKSHIRE HATHAWAY INC  —  2024-09-30
Total AUM: $266.4B

  APPLE INC                            $69,900.0M
  AMERICAN EXPRESS CO                  $41,100.0M
  BANK OF AMERICA CORP                 $31,700.0M
  COCA-COLA CO                         $28,700.0M
  CHEVRON CORP NEW                     $17,500.0M

Built-in CIK Constants

Skip the lookup — common institutions are pre-loaded:

EdgarAPI.BERKSHIRE    # 1067983 — Berkshire Hathaway
EdgarAPI.BRIDGEWATER  # 1350694 — Bridgewater Associates
EdgarAPI.CITADEL      # 1423053 — Citadel Advisors
EdgarAPI.RENAISSANCE  # 1037389 — Renaissance Technologies
EdgarAPI.VANGUARD     # 102909  — Vanguard Group
EdgarAPI.BLACKROCK    # 1364742 — BlackRock Inc.

API Reference

EdgarAPI(api_key)

api = EdgarAPI(api_key="YOUR_KEY")
# or use as a context manager:
with EdgarAPI(api_key="YOUR_KEY") as api:
    ...

holdings(cik, limit=100) → Portfolio

Get the latest 13F holdings for any institutional investor.

portfolio = api.holdings(EdgarAPI.CITADEL, limit=200)

print(portfolio.company_name)          # "CITADEL ADVISORS LLC"
print(portfolio.report_date)           # "2024-09-30"
print(portfolio.total_value_billions)  # 386.4
print(portfolio.total_holdings)        # 3412

# Top 10 positions
for h in portfolio.top(10):
    print(h.name_of_issuer, h.value_millions, h.shares)

Portfolio fields:

Field Type Description
cik int SEC Central Index Key
company_name str Institution name
report_date str Reporting period end date
total_value_usd int Total AUM in USD
total_holdings int Number of positions
holdings list[Holding] All positions
total_value_billions float AUM in billions (property)

Holding fields:

Field Type Description
name_of_issuer str Company name
title_of_class str Share class
cusip str CUSIP identifier
value_usd int Position value in USD
shares int Number of shares
share_type str e.g. "SH" or "PRN"
investment_discretion str "SOLE", "SHARED", etc.
value_millions float Value in millions (property)

search_companies(query, limit=10) → list[Company]

Search for companies by name or ticker symbol.

results = api.search_companies("Tesla", limit=5)
for c in results:
    print(c.cik, c.ticker, c.name)
# 1318605  TSLA  Tesla, Inc.

Company fields: cik, name, ticker

company(cik) → dict

Get a full company profile with recent SEC filings.

profile = api.company(320193)  # Apple Inc.
print(profile["name"])              # "Apple Inc."
print(profile["sic_description"])   # "Electronic Computers"
print(profile["ticker"])            # "AAPL"

for filing in profile["recent_filings"][:5]:
    print(filing["form"], filing["filed"], filing["description"])

search_filings(query="", form_type="", limit=20) → list[dict]

Search SEC filings across all filers.

# All recent 10-K annual reports
filings = api.search_filings(form_type="10-K", limit=10)

# Search by company name
filings = api.search_filings(query="Berkshire", form_type="13F-HR")

for f in filings:
    print(f["company_name"], f["form"], f["filed_date"])

Examples

Three ready-to-run scripts are in the examples/ directory:

Script What it does
berkshire_portfolio.py Prints Berkshire's full portfolio with weights
find_company.py Search for a company, view its profile and filings
track_changes.py Diff two quarters of holdings to spot new/closed/changed positions 
RAPIDAPI_KEY=your_key python examples/berkshire_portfolio.py
RAPIDAPI_KEY=your_key python examples/find_company.py "Nvidia"
RAPIDAPI_KEY=your_key python examples/track_changes.py

Full Example Output

============================================================
  BERKSHIRE HATHAWAY INC
  Report Date : 2024-09-30
  Total Value : $266.44B
  # Holdings  : 42
============================================================

Rank  Company                             Value ($M)     Weight     Shares
--------------------------------------------------------------------------------
1     APPLE INC                           $69,900.0      26.23%   300,000,000
2     AMERICAN EXPRESS CO                 $41,100.0      15.42%   151,610,700
3     BANK OF AMERICA CORP                $31,700.0      11.90%   903,799,600
4     COCA-COLA CO                        $28,700.0      10.77%   400,000,000
5     CHEVRON CORP NEW                    $17,500.0       6.57%   118,610,534
6     OCCIDENTAL PETROLEUM CORP           $13,000.0       4.88%   264,159,736
7     KRAFT HEINZ CO                       $9,600.0       3.60%   325,634,818
8     MOODY'S CORP                         $9,500.0       3.57%    24,669,778
9     DAVITA INC                           $4,600.0       1.73%    36,095,570
10    CITIGROUP INC                        $2,400.0       0.90%    55,244,797

Top 5 positions account for 70.89% of the portfolio.

Data Source

All data is sourced from official SEC EDGAR public filings, processed and served through the REST API.

Get your free API key on RapidAPI

License

MIT