.. image:: https://github.com/jadchaar/sec-edgar-downloader/workflows/tests/badge.svg?branch=master :alt: Build Status :target: https://github.com/jadchaar/sec-edgar-downloader/actions?query=branch%3Amaster+workflow%3Atests
.. image:: https://codecov.io/gh/jadchaar/sec-edgar-downloader/branch/master/graph/badge.svg :alt: Coverage Status :target: https://codecov.io/gh/jadchaar/sec-edgar-downloader
.. image:: https://img.shields.io/pypi/v/sec-edgar-downloader.svg :alt: PyPI Version :target: https://python.org/pypi/sec-edgar-downloader
.. image:: https://img.shields.io/pypi/pyversions/sec-edgar-downloader.svg :alt: Supported Python Versions :target: https://python.org/pypi/sec-edgar-downloader
.. image:: https://img.shields.io/pypi/l/sec-edgar-downloader.svg :alt: License :target: https://python.org/pypi/sec-edgar-downloader
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :alt: Code Style: Black :target: https://github.com/python/black
sec-edgar-downloader is a Python package for downloading company filings <https://en.wikipedia.org/wiki/SEC_filing> from the SEC EDGAR database <https://www.sec.gov/edgar/searchedgar/companysearch.html>.
Searches can be conducted either by stock ticker <https://en.wikipedia.org/wiki/Ticker_symbol>_ or Central Index Key (CIK) <https://en.wikipedia.org/wiki/Central_Index_Key>.
You can use the SEC CIK lookup tool <https://www.sec.gov/edgar/searchedgar/cik.htm> if you cannot find an appropriate ticker.
Installation ^^^^^^^^^^^^
Install and update this package using pip <https://pip.pypa.io/en/stable/quickstart/>_:
.. code-block:: console
$ pip install -U sec-edgar-downloaderBasic Usage ^^^^^^^^^^^
.. code-block:: python
from sec_edgar_downloader import Downloader
# Initialize a downloader instance. Download filings to the current
# working directory. Must declare company name and email address
# to form a user-agent string that complies with the SEC Edgar's
# programmatic downloading fair access policy.
# More info: https://www.sec.gov/os/webmaster-faq#code-support
# Company name and email are used to form a user-agent of the form:
# User-Agent: <Company Name> <Email Address>
dl = Downloader("MyCompanyName", "my.email@domain.com")
# 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: after and before strings must be in the form "YYYY-MM-DD"
dl.get("8-K", "AAPL", after="2017-01-01", before="2017-03-25")
# Get the five most recent 8-K filings for Apple
dl.get("8-K", "AAPL", limit=5)
# Get all 10-K filings for Microsoft
dl.get("10-K", "MSFT")
# Get the latest 10-K filing for Microsoft
dl.get("10-K", "MSFT", limit=1)
# 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")Advanced Usage ^^^^^^^^^^^^^^
.. code-block:: python
from sec_edgar_downloader import Downloader
# Download filings to the current working directory
dl = Downloader("MyCompanyName", "my.email@domain.com", "/path/to/save/location")
# Get all 10-K filings for Microsoft without the filing details
dl.get("10-K", "MSFT", download_details=False)
# Get the latest supported filings, if available, for Apple
for filing_type in dl.supported_filings:
dl.get(filing_type, "AAPL", limit=1)
# Get the latest supported filings, if available, for a
# specified list of tickers and CIKs
equity_ids = ["AAPL", "MSFT", "0000102909", "V", "FB"]
for equity_id in equity_ids:
for filing_type in dl.supported_filings:
dl.get(filing_type, equity_id, limit=1)This package supports downloading all SEC filing types (6-K, 8-K, 10-K, DEF 14A, S-1, and many others).
You can learn more about the different SEC filing types here <https://www.investopedia.com/articles/fundamental-analysis/08/sec-forms.asp>_).
Below is an exhaustive list of all filings types that can be downloaded by this package:
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 <https://github.com/jadchaar/sec-edgar-downloader/issues> or submit a pull request <https://help.github.com/en/articles/creating-a-pull-request>.
Development ^^^^^^^^^^^
In order to validate local code changes before creating a pull request, you can run the following commands:
.. code-block:: bash
# Run unit test suite on all locally-installed Python versions
$ tox
# Run unit test suite on a single Python version (e.g. Python 3.11)
$ tox -e py311
# Run end-to-end integration tests
$ tox -e integration
# Lint
$ tox -e lint
# Validate documentation
$ tox -e docsRelease ^^^^^^^
In order to create a new release, complete the following steps:
CHANGELOG.md._version.py and push change to master branch._version.py by running make tag.GitHub Actions release workflow <https://github.com/jadchaar/sec-edgar-downloader/actions/workflows/release.yml>_ will be kicked off that automatically creates the package artifacts and uploads them to PyPI.GitHub repository's release page <https://github.com/jadchaar/sec-edgar-downloader/releases>_.For full documentation, please visit sec-edgar-downloader.readthedocs.io <https://sec-edgar-downloader.readthedocs.io>_.