Downloader
The Downloader module provides functionality for downloading SEC filings and related data.
Basic Usage
downloader = dm.Downloader()
Downloading Filings
The downloader uses the EFTS API to retrieve filing locations, and the SEC API to download filings.
Note: form is root form type (e.g., ‘10-K’ includes ‘10-K/A’). To filter use file_types set to e.g. ‘10-K’. Note: Current filing system can’t distinguish between 10-K and 10-KSB (phased out in 2009). I’m working on a solution for this.
Parameters
The download()
method accepts the following parameters:
output_dir (str, optional): Directory where downloaded filings will be saved. Defaults to ‘filings’.
return_urls (bool, optional): If True, returns list of filing URLs instead of downloading them. Defaults to False.
cik (str|list, optional): Central Index Key(s) of companies. Can be single CIK or list of CIKs. Will be zero-padded to 10 digits.
ticker (str|list, optional): Stock ticker symbol(s). Will be converted to CIK. Mutually exclusive with cik parameter.
- form (str|list, optional): SEC form type(s) to download. Forms include all variations (e.g., ‘10-K’ includes ‘10-K/A’). Examples:
Single form: “10-K”, “10-Q”, “8-K”
Multiple forms: [“10-K”, “10-Q”]
Defaults to “-0” (all forms)
- date (str|tuple|list, optional): Filing date criteria. Can be:
Single date: “2023-01-01”
Date range tuple: (“2023-01-01”, “2023-12-31”)
List of dates: [“2023-01-01”, “2023-02-01”]
Defaults to all dates from 2001-01-01 to present
sics (list, optional): Standard Industrial Classification codes to filter by. Example: [1311, 2834]
items (list, optional): Form-specific item numbers to filter by. Example: [“1.01”, “2.01”] for 8-K items
file_types (str|list, optional): Types of files to download, such as exhibits. Examples: “EX-10”, [“EX-10”, “EX-21”]
Examples
# Download all 10-K filings (including 10-K/A) for Tesla using CIK
downloader.download(form='10-K', cik='1318605', output_dir='filings')
# Download 10-K filings for multiple companies using tickers
downloader.download(form='10-K', ticker=['TSLA', 'META'], output_dir='filings')
# Download every form 3 for a specific date
downloader.download(form='3', date='2024-05-21', output_dir='filings')
# Download filings with specific exhibit types
downloader.download(form='10-K', ticker='AAPL', file_types=['EX-10', 'EX-21'])
# Download 8-K filings with specific items
downloader.download(form='8-K', ticker='TSLA', items=['1.01', '2.01'])
Rate Limits
The default rate limit is set to 10 requests/second. For downloading more than 5,000 filings I advise setting a lower rate limit to avoid being limited by the SEC. This is because there is a hidden, undocumented rate limit per ten minutes that limits you to ~5/second.
downloader.set_limiter('www.sec.gov', 5)
downloader.set_limiter('efts.sec.gov', 5) # This is likely unnecessary as EFTS API does not appear to have rate limits
Monitoring New Filings
You can watch for new filings:
downloader.watch(interval=1, form='8-K', ticker='AAPL')
Misc Information
The downloader can not distinguish between 10-K and 10-KSB (phased out in 2009).