sec-edgar-downloader

Build Status Coverage Status PyPI Version Supported Python Versions License Code Style: Black

sec-edgar-downloader is a Python package for downloading company filings from the SEC EDGAR database. Searches can be conducted either by stock ticker or Central Index Key (CIK). You can use the SEC CIK lookup tool if you cannot find an appropriate ticker.

Quick Start

Installation

Install and update this package using pip or pipenv:

$ pip install -U sec-edgar-downloader

Example Usage

from sec_edgar_downloader import Downloader

# Initialize a downloader instance.
# If no argument is passed to the constructor, the package
# will attempt to locate the user's downloads folder.
dl = Downloader("/path/to/valid/save/location")

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

# Get all 8-K filings for Apple, including filing amends (8-K/A)
dl.get("8-K", "AAPL", include_amends=True)

# Get all 8-K filings for Apple after January 1, 2017 and before March 25, 2017
# Note: before_date and after_date strings must be in the form "YYYYMMDD"
dl.get("8-K", "AAPL", after_date="20170101", before_date="20170325")

# Get the five most recent 8-K filings for Apple
dl.get("8-K", "AAPL", 5)

# Get all 10-K filings for Microsoft (ticker: MSFT)
dl.get("10-K", "MSFT")

# Get the latest 10-K filing for Microsoft
dl.get("10-K", "MSFT", 1)

# Get the latest 10KSB filing for Ubiquitech Software
dl.get("10KSB", "0001411460", 1)

# Get all 10-Q filings for Visa (ticker: V)
dl.get("10-Q", "V")

# Get all 13F-NT filings for the Vanguard Group (CIK: 0000102909)
dl.get("13F-NT", "0000102909")

# Get all 13F-HR filings for the Vanguard Group
dl.get("13F-HR", "0000102909")

# Get all SC 13G filings for Apple
dl.get("SC 13G", "AAPL")

# Get all SD filings for Apple
dl.get("SD", "AAPL")

# Get the latest supported filings, if available, for Apple
for filing_type in dl.supported_filings:
    dl.get(filing_type, "AAPL", 1)

# Get the latest supported filings, if available, for a
# specified list of tickers and CIKs
symbols = ["AAPL", "MSFT", "0000102909", "V", "FB"]
for s in symbols:
    for filing_type in dl.supported_filings:
        dl.get(filing_type, s, 1)

Supported SEC Filings

  • 4
  • 8-K
  • 10-K
  • 10KSB
  • 10-Q
  • 13F-NT and 13F-HR
  • 20-F
  • SC 13G
  • SD
  • S-1
  • DEF 14A

You can learn more about the different types of SEC filings here.

Contributing

If you encounter a bug or would like to see a new company filing or feature added to sec-edgar-downloader, please file an issue or submit a pull request.

Documentation

For full documentation, please visit sec-edgar-downloader.readthedocs.io.

API Guide

sec_edgar_downloader.Downloader

Provides the Downloader class, which is used to download SEC filings.

class sec_edgar_downloader.Downloader.Downloader(download_folder=None)

A Downloader object.

Parameters:download_folder (str, optional) – relative or absolute path to download location, defaults to the user’s Downloads folder.

Usage:

>>> from sec_edgar_downloader import Downloader
>>> dl = Downloader()
supported_filings

Get a sorted list of all supported filings.

Returns:sorted list of all supported filings.
Return type:list

Usage:

>>> from sec_edgar_downloader import Downloader
>>> dl = Downloader()
>>> dl.supported_filings
['10-K', '10-Q', '10KSB', '13F-HR', '13F-NT', '8-K', 'SC 13G', 'SD']
get(filing_type, ticker_or_cik, num_filings_to_download=None, after_date=None, before_date=None, include_amends=False)

Downloads filing documents and saves them to disk.

Parameters:
  • filing_type (str) – type of filing to download
  • ticker_or_cik (str) – ticker or CIK to download filings for
  • num_filings_to_download (int, optional) – number of filings to download, defaults to all available filings
  • after_date (str, optional) – date of form YYYYMMDD in which to download filings after, defaults to None
  • before_date (str, optional) – date of form YYYYMMDD in which to download filings before, defaults to today
  • include_amends (bool, optional) – denotes whether or not to include filing amends (e.g. 8-K/A), defaults to False
Returns:

number of filings downloaded

Return type:

int

Usage:

>>> from sec_edgar_downloader import Downloader
>>> dl = Downloader()

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

# Get all 8-K filings for Apple, including filing amends (8-K/A)
>>> dl.get("8-K", "AAPL", include_amends=True)

# Get all 8-K filings for Apple after January 1, 2017 and before March 25, 2017
>>> dl.get("8-K", "AAPL", after_date="20170101", before_date="20170325")

# Get the five most recent 10-K filings for Apple
>>> dl.get("10-K", "AAPL", 5)

# Get all 10-Q filings for Visa
>>> dl.get("10-Q", "V")

# Get all 13F-NT filings for the Vanguard Group
>>> dl.get("13F-NT", "0000102909")

# Get all 13F-HR filings for the Vanguard Group
>>> dl.get("13F-HR", "0000102909")

# Get all SC 13G filings for Apple
>>> dl.get("SC 13G", "AAPL")

# Get all SD filings for Apple
>>> dl.get("SD", "AAPL")