DOCSEARCHbyAlgolia
Submit Docs

sec-edgar-downloader

repository·master·Indexed 20 days ago

https://github.com/jadchaar/sec-edgar-downloader

A Python package for downloading company filings from the SEC EDGAR database using stock tickers or Central Index Keys (CIK). It includes a Downloader class to fetch specific filing types (e.g., 10-K, 8-K) with support for date filtering, amendment inclusion, and automated compliance with the SEC's programmatic downloading fair access policy via required User-Agent strings.

Tokens
6.6K
Snippets
24
Records
25
Agent score
72%

What's inside sec-edgar-downloader

  1. Initialize the Downloader and comply with SEC fair access policy

    master

    To use the Downloader, you must provide a company name and an email address. These are used to construct a User-Agent string (format: User-Agent: <Company Name> <Email Address>) required by the SEC EDGAR programmatic downloading fair access policy.

    By default, filings are downloaded to the current working directory. You can specify a custom download path during initialization.

    from sec_edgar_downloader import Downloader

# Download to current working directory
dl = Downloader("MyCompanyName", "my.email@domain.com")

# Download to a specific path
dl = Downloader("MyCompanyName", "my.email@domain.com", "/path/to/save/location")

  3. Quick Start with sec-edgar-downloader

    master

    To use sec-edgar-downloader, initialize a Downloader instance. You must provide a company name and an email address; these are used to construct a User-Agent string (e.g., User-Agent: <Company Name> <Email Address>) to comply with the SEC Edgar programmatic downloading fair access policy. Filings are downloaded to the current working directory by default.

    For more details on the SEC's policy, visit: https://www.sec.gov/os/webmaster-faq#code-support

    from sec_edgar_downloader import Downloader

# Initialize the downloader with your company name and email
downloader = Downloader("MyCompany", "my@email.com")

# Example: Get all 8-K filings for Apple (ticker: AAPL)
downloader.get("8-K", "AAPL")

# Example: Get all 8-K filings for Apple, including filing amends (8-K/A)
downloader.get("8-K", "AAPL", after="2023-01-01")

# Example: Get filings within a specific date range
downloader.get("8-K", "AAPL", after="2017-01-01", before="2017-03-25")

  4. Understand SEC rate limiting and throttling

    master

    The library implements a global rate limit to comply with the SEC's fair access policy, which allows a maximum of 10 requests per second.

    • The limiter uses SEC_THROTTLE_LIMIT_RATE to ensure compliance.
    • In version 4.x and later, the limiter is configured with blocking=True by default, meaning the execution will wait until a permit is available rather than raising an error.
    • A small delay buffer (buffer_ms, default: 50ms) is used to account for timing variations and prevent hitting the limit exactly.

  5. Initialize the Downloader

    master

    To use sec-edgar-downloader, you must first instantiate a Downloader object.

    Important Compliance Requirement: To comply with the SEC Edgar programmatic downloading fair access policy, you must provide a company_name and an email_address. These are used to form the User-Agent header in the format: User-Agent: <Company Name> <Email Address>.

    You can also specify a download_folder (relative or absolute path) where filings will be saved. If not provided, it defaults to the current working directory.

    from sec_edgar_downloader import Downloader

# Download to current working directory
dl = Downloader("MyCompanyName", "my.email@domain.com")

# Download to a specific path
dl = Downloader("MyCompanyName", "my.email@domain.com", "/path/to/save/location")

  6. Iterate through supported filing types

    master

    The Downloader instance provides a supported_filings attribute, which is an iterable of all filing types currently supported by the package. You can use this to loop through and download the latest available filings for a company.

    from sec_edgar_downloader import Downloader

dl = Downloader("MyCompanyName", "my.email@domain.com")

# Get the latest supported filing for Apple
for filing_type in dl.supported_filings:
    dl.get(filing_type, "AAPL", limit=1)

  7. Download SEC filings using Downloader.get()

    master

    The get() method is used to download specific filing types for a company identified by its stock ticker or Central Index Key (CIK).

    Parameters:

    • filing_type (str): The type of SEC filing (e.g., '10-K', '8-K').
    • equity_id (str): The stock ticker or CIK.
    • include_amends (bool, optional): If True, includes filing amendments (e.g., 8-K/A).
    • after (str, optional): Filter filings after this date (format: "YYYY-MM-DD").
    • before (str, optional): Filter filings before this date (format: "YYYY-MM-DD").
    • limit (int, optional): The maximum number of filings to download.
    • download_details (bool, optional): If False, downloads the filing without additional details.
    from sec_edgar_downloader import Downloader

dl = Downloader("MyCompanyName", "my.email@domain.com")

# Basic usage
dl.get("8-K", "AAPL")

# Including amendments
dl.get("8-K", "AAPL", include_amends=True)

# Date range filtering
dl.get("8-K", "AAPL", after="2017-01-01", before="2017-03-25")

# Limiting results
dl.get("8-K", "AAPL", limit=5)

# Using CIK instead of ticker
dl.get("13F-HR", "0000102909")

# Without filing details
dl.get("10-K", "MSFT", download_details=False)

  8. Reference: Supported SEC filing types

    master

    The following is an exhaustive list of all filing types that can be downloaded using sec-edgar-downloader.

    1, 1-A, 1-A POS, 1-A-W, 1-E, 1-E AD, 1-K, 1-SA, 1-U, 1-Z, 1-Z-W, 10-12B, 10-12G, 10-D, 10-K, 10-KT, 10-Q, 10-QT, 11-K, 11-KT, 13F-HR, 13F-NT, 13FCONP, 144, 15-12B, 15-12G, 15-15D, 15F-12B, 15F-12G, 15F-15D, 18-12B, 18-K, 19B-4E, 2-A, 2-AF, 2-E, 20-F, 20FR12B, 20FR12G, 24F-2NT, 25, 25-NSE, 253G1, 253G2, 253G3, 253G4, 3, 305B2, 34-12H, 4, 40-17F1, 40-17F2, 40-17G, 40-17GCS, 40-202A, 40-203A, 40-206A, 40-24B2, 40-33, 40-6B, 40-8B25, 40-8F-2, 40-APP, 40-F, 40-OIP, 40FR12B, 40FR12G, 424A, 424B1, 424B2, 424B3, 424B4, 424B5, 424B7, 424B8, 424H, 425, 485APOS, 485BPOS, 485BXT, 486APOS, 486BPOS, 486BXT, 487, 497, 497AD, 497H2, 497J, 497K, 5, 6-K, 6B NTC, 6B ORDR, 8-A12B, 8-A12G, 8-K, 8-K12B, 8-K12G3, 8-K15D5, 8-M, 8F-2 NTC, 8F-2 ORDR, 9-M, ABS-15G, ABS-EE, ADN-MTL, ADV-E, ADV-H-C, ADV-H-T, ADV-NR, ANNLRPT, APP NTC, APP ORDR, APP WD, APP WDG, ARS, ATS-N, ATS-N-C, ATS-N/UA, AW, AW WD, C, C-AR, C-AR-W, C-TR, C-TR-W, C-U, C-U-W, C-W, CB, CERT, CERTARCA, CERTBATS, CERTCBO, CERTNAS, CERTNYS, CERTPAC, CFPORTAL, CFPORTAL-W, CORRESP, CT ORDER, D, DEF 14A, DEF 14C, DEFA14A, DEFA14C, DEFC14A, DEFC14C, DEFM14A, DEFM14C, DEFN14A, DEFR14A, DEFR14C, DEL AM, DFAN14A, DFRN14A, DOS, DOSLTR, DRS, DRSLTR, DSTRBRPT, EFFECT, F-1, F-10, F-10EF, F-10POS, F-1MEF, F-3, F-3ASR, F-3D, F-3DPOS, F-3MEF, F-4, F-4 POS, F-4MEF, F-6, F-6 POS, F-6EF, F-7, F-7 POS, F-8, F-8 POS, F-80, F-80POS, F-9, F-9 POS, F-N, F-X, FOCUSN, FWP, G-405, G-405N, G-FIN, G-FINW, IRANNOTICE, MA, MA-A, MA-I, MA-W, MSD, MSDCO, MSDW, N-1, N-14, N-14 8C, N-14MEF, N-18F1, N-1A, N-2, N-23C-2, N-23C3A, N-23C3B, N-23C3C, 2MEF, N-30B-2, N-30D, N-4, N-5, N-54A, N-54C, N-6, N-6F, N-8A, N-8B-2, N-8F, N-8F NTC, N-8F ORDR, N-CEN, N-CR, N-CSR, N-CSRS, N-MFP, N-MFP1, N-MFP2, N-MFP3, N-PX, N-Q, NO ACT, NPORT-EX, NPORT-NP, NPORT-P, NRSRO-CE, NRSRO-UPD, NSAR-A, NSAR-AT, NSAR-B, NSAR-BT, NSAR-U, NT 10-D, NT 10-K, NT 10-Q, NT 11-K, NT 20-F, NT N-CEN, NT N-MFP, NT N-MFP1, NT N-MFP2, NT NPORT-EX, NT NPORT-P, NT-NCEN, NT-NCSR, NT-NSAR, NTFNCEN, NTFNCSR, NTFNSAR, NTN 10D, NTN 10K, NTN 10Q, NTN 20F, OIP NTC, OIP ORDR, POS 8C, POS AM, POS AMI, POS EX, POS462B, POS462C, POSASR, PRE 14A, PRE 14C, PREC14A, PREC14C, PREM14A, PREM14C, PREN14A, PRER14A, PRER14C, PRRN14A, PX14A6G, PX14A6N, QRTLYRPT, QUALIF, REG-NR, REVOKED, RW, RW WD, S-1, S-11, S-11MEF, S-1MEF, S-20, S-3, S-3ASR, S-3D, S-3DPOS, S-3MEF, S-4, S-4 POS, S-4EF, S-4MEF, S-6, S-8, S-8 POS, S-B, S-BMEF, SC 13D, SC 13E1, SC 13E3, SC 13G, SC 14D9, SC 14F1, SC 14N, SC TO-C, SC TO-I, SC TO-T, SC13E4F, SC14D1F, SC14D9C, SC14D9F, SD, SDR, SE, SEC ACTION, SEC STAFF ACTION, SEC STAFF LETTER, SF-1, SF-3, SL, SP 15D2, STOP ORDER, SUPPL, T-3, TA-1, TA-2, TA-W, TACO, TH, TTW, UNDER, UPLOAD, WDL-REQ, X-17A-5

  10. Validate and convert a ticker or CIK

    master

    Use validate_and_convert_ticker_or_cik to normalize a company identifier. It accepts either a ticker symbol or a Central Index Key (CIK).

    • If a CIK is provided, the function ensures it is zero-padded to the required length (10 digits) for SEC Edgar APIs. If the CIK exceeds the maximum allowed length, it raises a ValueError.
    • If a ticker is provided, the function uses the provided ticker_to_cik_mapping dictionary to look up the corresponding CIK. If the ticker cannot be mapped, it raises a ValueError.
    • Input strings are automatically stripped of whitespace and converted to uppercase.
    from typing import Dict
from sec_edgar_downloader._utils import validate_and_convert_ticker_or_cik

ticker_mapping = {"AAPL": "0000320193"}

# Converting a ticker
cik = validate_and_convert_ticker_or_cik("aapl", ticker_mapping)
print(cik)  # Output: '0000320193'

# Converting a CIK (handles zero-padding)
cik_padded = validate_and_convert_ticker_or_cik("320193", ticker_mapping)
print(cik_padded)  # Output: '0000320193'

  11. Download filings using Downloader.get()

    master

    The get() method is the primary way to download SEC filings. It accepts a form type and either a ticker symbol or a CIK (Central Index Key).

    Parameters:

    • form (str): The type of form to download (e.g., 8-K, 10-K, 10-Q).
    • ticker_or_cik (str): The company's ticker symbol or CIK.
    • limit (int, optional): Maximum number of filings to download. Defaults to all available filings.
    • after (Date/str, optional): Filings must be after this date (format YYYY-MM-DD or datetime object). Defaults to 1994-01-01.
    • before (Date/str, optional): Filings must be before this date (format YYYY-MM-DD or datetime object). Defaults to today.
    • include_amends (bool): If True, includes filing amendments (e.g., 8-K/A). Defaults to False.
    • download_details (bool): If True, downloads human-readable/parseable detail documents (e.g., XML or HTML). Defaults to False.
    • accession_numbers_to_skip (Set[str], optional): A set of accession numbers to ignore during the download process.

    Returns:

    • int: The total number of filings successfully downloaded.
    from sec_edgar_downloader import Downloader

dl = Downloader("MyCompanyName", "my.email@domain.com")

# Basic usage: Get all 8-K filings for Apple
dl.get("8-K", "AAPL")

# Filter by date range
dl.get("8-K", "AAPL", after="2017-01-01", before="2017-03-25")

# Limit the number of results
dl.get("10-K", "AAPL", limit=5)

# Include amendments (e.g., 8-K/A)
dl.get("8-K", "AAPL", include_amends=True)

# Use CIK instead of ticker
dl.get("13F-NT", "0000102909")

  12. Get available filings list with get_list_of_available_filings()

    master

    Use get_list_of_available_filings(uri, user_agent) to retrieve a JSON list of available filings for a given URI. This function targets HOST_DATA_SEC to fetch metadata.

    # Example usage (requires valid uri and user_agent)
filings_data = get_list_of_available_filings("https://example.sec.gov/api/filings", "MyCompany myemail@example.com")