sec-downloader

A better version of sec-edgar-downloader. Includes an alternative implementation (a wrapper instead of a fork), to keep compatibility with new sec-edgar-downloader releases. This library partially uses nbdev.

Features

Advantages over sec-edgar-downloader:

Flexibility in Download Process

Tailored for choosing what, where, and how to download.
Files stored in memory for faster operations and no unnecessary disk

clutter.

Separate Metadata and File Downloads

Easily skip unneeded files.
Download metadata first, then selectively download files.
Option to save metadata for better organization.

More Input Options

Ticker or CIK (e.g., AAPL, 0000320193) for latest filings.
Accession Number (e.g., 0000320193-23-000077). Not supported in

sec-edgar-downloader.

SEC EDGAR URL (e.g.,

https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm). Not supported in sec-edgar-downloader.

Install

sh
pip install sec-downloader

How to use

Download the metadata

Note The company name and email address are used to form a

user-agent string that adheres to the SEC EDGAR’s fair access policy

for programmatic downloading.

Source

python
from sec_downloader import Downloader
dl = Downloader("MyCompanyName", "email@example.com")

Find a filing with an Accession Number

python
metadatas = dl.getfilingmetadatas("AAPL/0000320193-23-000077")
print(metadatas)

[FilingMetadata(accessi, form_type='10-Q', primarydocurl='https://www.sec.gov/Archives/edgar/data/320193/000032019323000077/aapl-20230701.htm', items='', primarydocdescription='10-Q', filing_date='2023-08-04', report_date='2023-07-01', cik='0000320193', company_name='Apple Inc.', tickers=[Ticker(symbol='AAPL', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

metadatas = dl.getfilingmetadatas("aapl/000032019323000077") metadatas = dl.getfilingmetadatas("320193/000032019323000077") metadatas = dl.getfilingmetadatas("320193/0000320193-23-000077") metadatas = dl.getfilingmetadatas("0000320193/0000320193-23-000077") metadatas = dl.getfilingmetadatas(CompanyAndAccessionNumber(tickerorcik="320193", accessi))

Find the filing matching a SEC EDGAR Filing URL. Only CIK and Accession Number are used from the URL:

python
metadatas = dl.getfilingmetadatas(
    "https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm"
)
print(metadatas)

[FilingMetadata(accessi, form_type='8-K', primarydocurl='https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm', items='2.02,9.01', primarydocdescription='8-K', filing_date='2023-11-07', report_date='2023-11-04', cik='0001067983', company_name='BERKSHIRE HATHAWAY INC', tickers=[Ticker(symbol='BRK-B', exchange='NYSE'), Ticker(symbol='BRK-A', exchange='NYSE')])]

Alternatively, you can also URLs in other formats and get the same answer:

metadatas = dl.getfilingmetadatas("https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm")

Find latest filings by company ticker or CIK:

python
from sec_downloader.types import RequestedFilings
metadatas = dl.getfilingmetadatas(     RequestedFilings(tickerorcik="MSFT", form_type="10-K", limit=2) ) print(metadatas)

[FilingMetadata(accessi, form_type='10-K', primarydocurl='https://www.sec.gov/Archives/edgar/data/789019/000095017024087843/msft-20240630.htm', items='', primarydocdescription='10-K', filing_date='2024-07-30', report_date='2024-06-30', cik='0000789019', company_name='MICROSOFT CORP', tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')]), FilingMetadata(accessi, form_type='10-K', primarydocurl='https://www.sec.gov/Archives/edgar/data/789019/000095017023035122/msft-20230630.htm', items='', primarydocdescription='10-K', filing_date='2023-07-27', report_date='2023-06-30', cik='0000789019', company_name='MICROSOFT CORP', tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

metadatas = dl.getfilingmetadatas("2/msft/10-K") metadatas = dl.getfilingmetadatas("2/789019/10-K") metadatas = dl.getfilingmetadatas("2/0000789019/10-K")

The parameters limit and form_type are optional. If omitted, limit defaults to 1, and form_type defaults to ‘10-Q’.

python
metadatas = dl.getfilingmetadatas("NFLX")
print(metadatas)

[FilingMetadata(accessi, form_type='10-Q', primarydocurl='https://www.sec.gov/Archives/edgar/data/1065280/000106528024000287/nflx-20240930.htm', items='', primarydocdescription='10-Q', filing_date='2024-10-18', report_date='2024-09-30', cik='0001065280', company_name='NETFLIX INC', tickers=[Ticker(symbol='NFLX', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

metadatas = dl.getfilingmetadatas("nflx") metadatas = dl.getfilingmetadatas("1/NFLX") metadatas = dl.getfilingmetadatas("NFLX/10-Q") metadatas = dl.getfilingmetadatas("1/NFLX/10-Q") metadatas = dl.getfilingmetadatas(RequestedFilings(tickerorcik="NFLX")) metadatas = dl.getfilingmetadatas(RequestedFilings(limit=1, tickerorcik="NFLX", form_type="10-Q"))

Download the HTML files

After obtaining the Primary Document URL, for example from the metadata, you can proceed to download the HTML using this URL.

python
for metadata in metadatas:
    html = dl.downloadfiling(url=metadata.primarydoc_url).decode()
    print(html[:50])
    break  # same for all filings, let's just print the first one

"\n