{"id":21915662,"url":"https://github.com/elijas/sec-downloader","last_synced_at":"2025-04-06T12:07:58.754Z","repository":{"id":199783106,"uuid":"703821333","full_name":"Elijas/sec-downloader","owner":"Elijas","description":"Find and download SEC filings. Built on top of sec-edgar-downloader.","archived":false,"fork":false,"pushed_at":"2025-02-13T01:26:59.000Z","size":444,"stargazers_count":37,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T11:06:29.613Z","etag":null,"topics":["company-data","edgar","edgar-api","edgar-downloader","filings","finance","financial","financial-data","financial-filings","fintech","investing","mutual-funds","python","sec","sec-edgar","sec-edgar-api","sec-edgar-downloader","stock-market","stocks"],"latest_commit_sha":null,"homepage":"https://elijas.github.io/sec-downloader/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Elijas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-10-12T01:49:45.000Z","updated_at":"2025-03-28T23:41:56.000Z","dependencies_parsed_at":"2023-11-14T02:51:01.748Z","dependency_job_id":null,"html_url":"https://github.com/Elijas/sec-downloader","commit_stats":null,"previous_names":["elijas/sec-downloader"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fsec-downloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fsec-downloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fsec-downloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fsec-downloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Elijas","download_url":"https://codeload.github.com/Elijas/sec-downloader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478319,"owners_count":20945266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["company-data","edgar","edgar-api","edgar-downloader","filings","finance","financial","financial-data","financial-filings","fintech","investing","mutual-funds","python","sec","sec-edgar","sec-edgar-api","sec-edgar-downloader","stock-market","stocks"],"created_at":"2024-11-28T19:13:18.015Z","updated_at":"2025-04-06T12:07:58.736Z","avatar_url":"https://github.com/Elijas.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sec-downloader\n\n\u003c!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! --\u003e\n\n\u003ca href=\"https://github.com/elijas/sec-downloader/actions/workflows/test.yaml\"\u003e\u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/elijas/sec-downloader/test.yaml?label=build\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/sec-downloader/\"\u003e\u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/sec-downloader\"\u003e\u003c/a\u003e\n\u003ca href=\"https://badge.fury.io/py/sec-downloader\"\u003e\u003cimg src=\"https://badge.fury.io/py/sec-downloader.svg\" alt=\"PyPI version\" /\u003e\u003c/a\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/elijas/sec-downloader.svg\" alt=\"Licence\"\u003e\u003c/a\u003e\n\nA better version of `sec-edgar-downloader`. Includes an alternative\nimplementation (a wrapper instead of a fork), to keep compatibility with\nnew `sec-edgar-downloader` releases. This library partially uses\n[nbdev](https://nbdev.fast.ai/).\n\n# Features\n\nAdvantages over `sec-edgar-downloader`:\n\n**Flexibility in Download Process**\n\n- Tailored for choosing *what*, *where*, and *how* to download.\n- Files stored in memory for faster operations and no unnecessary disk\n  clutter.\n\n**Separate Metadata and File Downloads**\n\n- Easily skip unneeded files.\n- Download metadata first, then selectively download files.\n- Option to save metadata for better organization.\n\n**More Input Options**\n\n- Ticker or CIK (e.g., `AAPL`, `0000320193`) for latest filings.\n- Accession Number (e.g., `0000320193-23-000077`). Not supported in\n  `sec-edgar-downloader`.\n- SEC EDGAR URL (e.g.,\n  `https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm`).\n  Not supported in `sec-edgar-downloader`.\n\n# Install\n\n``` sh\npip install sec-downloader\n```\n\n# How to use\n\n## Download the metadata\n\n\u003e **Note** The company name and email address are used to form a\n\u003e user-agent string that adheres to the SEC EDGAR’s fair access policy\n\u003e for programmatic downloading.\n\u003e [Source](https://www.sec.gov/os/webmaster-faq#code-support)\n\n``` python\nfrom sec_downloader import Downloader\n\ndl = Downloader(\"MyCompanyName\", \"email@example.com\")\n```\n\nFind a filing with an Accession Number\n\n``` python\nmetadatas = dl.get_filing_metadatas(\"AAPL/0000320193-23-000077\")\nprint(metadatas)\n```\n\n    [FilingMetadata(accession_number='0000320193-23-000077',\n                    form_type='10-Q',\n                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/320193/000032019323000077/aapl-20230701.htm',\n                    items='',\n                    primary_doc_description='10-Q',\n                    filing_date='2023-08-04',\n                    report_date='2023-07-01',\n                    cik='0000320193',\n                    company_name='Apple Inc.',\n                    tickers=[Ticker(symbol='AAPL', exchange='Nasdaq')])]\n\nAlternatively, you can also use any of these to get the same answer:\n\n    metadatas = dl.get_filing_metadatas(\"aapl/000032019323000077\")\n    metadatas = dl.get_filing_metadatas(\"320193/000032019323000077\")\n    metadatas = dl.get_filing_metadatas(\"320193/0000320193-23-000077\")\n    metadatas = dl.get_filing_metadatas(\"0000320193/0000320193-23-000077\")\n    metadatas = dl.get_filing_metadatas(CompanyAndAccessionNumber(ticker_or_cik=\"320193\", accession_number=\"0000320193-23-000077\"))\n\nFind the filing matching a SEC EDGAR Filing URL. Only CIK and Accession\nNumber are used from the URL:\n\n``` python\nmetadatas = dl.get_filing_metadatas(\n    \"https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm\"\n)\nprint(metadatas)\n```\n\n    [FilingMetadata(accession_number='0001193125-23-272204',\n                    form_type='8-K',\n                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm',\n                    items='2.02,9.01',\n                    primary_doc_description='8-K',\n                    filing_date='2023-11-07',\n                    report_date='2023-11-04',\n                    cik='0001067983',\n                    company_name='BERKSHIRE HATHAWAY INC',\n                    tickers=[Ticker(symbol='BRK-B', exchange='NYSE'),\n                             Ticker(symbol='BRK-A', exchange='NYSE')])]\n\nAlternatively, you can also URLs in other formats and get the same\nanswer:\n\n    metadatas = dl.get_filing_metadatas(\"https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm\")\n\nFind latest filings by company ticker or CIK:\n\n``` python\nfrom sec_downloader.types import RequestedFilings\n\nmetadatas = dl.get_filing_metadatas(\n    RequestedFilings(ticker_or_cik=\"MSFT\", form_type=\"10-K\", limit=2)\n)\nprint(metadatas)\n```\n\n    [FilingMetadata(accession_number='0000950170-24-087843',\n                    form_type='10-K',\n                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/789019/000095017024087843/msft-20240630.htm',\n                    items='',\n                    primary_doc_description='10-K',\n                    filing_date='2024-07-30',\n                    report_date='2024-06-30',\n                    cik='0000789019',\n                    company_name='MICROSOFT CORP',\n                    tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')]),\n     FilingMetadata(accession_number='0000950170-23-035122',\n                    form_type='10-K',\n                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/789019/000095017023035122/msft-20230630.htm',\n                    items='',\n                    primary_doc_description='10-K',\n                    filing_date='2023-07-27',\n                    report_date='2023-06-30',\n                    cik='0000789019',\n                    company_name='MICROSOFT CORP',\n                    tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')])]\n\nAlternatively, you can also use any of these to get the same answer:\n\n    metadatas = dl.get_filing_metadatas(\"2/msft/10-K\")\n    metadatas = dl.get_filing_metadatas(\"2/789019/10-K\")\n    metadatas = dl.get_filing_metadatas(\"2/0000789019/10-K\")\n\nThe parameters `limit` and `form_type` are optional. If omitted, `limit`\ndefaults to 1, and `form_type` defaults to ‘10-Q’.\n\n``` python\nmetadatas = dl.get_filing_metadatas(\"NFLX\")\nprint(metadatas)\n```\n\n    [FilingMetadata(accession_number='0001065280-24-000287',\n                    form_type='10-Q',\n                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/1065280/000106528024000287/nflx-20240930.htm',\n                    items='',\n                    primary_doc_description='10-Q',\n                    filing_date='2024-10-18',\n                    report_date='2024-09-30',\n                    cik='0001065280',\n                    company_name='NETFLIX INC',\n                    tickers=[Ticker(symbol='NFLX', exchange='Nasdaq')])]\n\nAlternatively, you can also use any of these to get the same answer:\n\n    metadatas = dl.get_filing_metadatas(\"nflx\")\n    metadatas = dl.get_filing_metadatas(\"1/NFLX\")\n    metadatas = dl.get_filing_metadatas(\"NFLX/10-Q\")\n    metadatas = dl.get_filing_metadatas(\"1/NFLX/10-Q\")\n    metadatas = dl.get_filing_metadatas(RequestedFilings(ticker_or_cik=\"NFLX\"))\n    metadatas = dl.get_filing_metadatas(RequestedFilings(limit=1, ticker_or_cik=\"NFLX\", form_type=\"10-Q\"))\n\n## Download the HTML files\n\nAfter obtaining the Primary Document URL, for example from the metadata,\nyou can proceed to download the HTML using this URL.\n\n``` python\nfor metadata in metadatas:\n    html = dl.download_filing(url=metadata.primary_doc_url).decode()\n    print(html[:50])\n    break  # same for all filings, let's just print the first one\n```\n\n    \"\u003c?xml version='1.0' encoding='ASCII'?\u003e\\n\u003c!--XBRL Do\"\n\n# Alternative implementation: Wrapper\n\nFiles are downloaded to a temporary folder, immediately read into\nmemory, and then deleted. Let’s demonstrate how to download a single\nfile (latest 10-Q filing details in HTML format) to memory. The “glob”\npattern is used to select which files are read to memory.\n\n``` python\nfrom sec_edgar_downloader import Downloader as SecEdgarDownloader\nfrom sec_downloader.download_storage import DownloadStorage\n\nONLY_HTML = \"**/*.htm*\"\n\nstorage = DownloadStorage(filter_pattern=ONLY_HTML)\nwith storage as path:\n    dl = SecEdgarDownloader(\"MyCompanyName\", \"email@example.com\", path)\n    dl.get(\"10-Q\", \"AAPL\", limit=1, download_details=True)\n# all files are now deleted and only stored in memory\n\ncontent = storage.get_file_contents()[0].content\nprint(f\"{content[:50]}...\")\n```\n\n    \"\u003c?xml version='1.0' encoding='ASCII'?\u003e\\n\u003c!--XBRL Do...\"\n\nDownloading multiple documents:\n\n``` python\nstorage = DownloadStorage()\nwith storage as path:\n    dl = SecEdgarDownloader(\"MyCompanyName\", \"email@example.com\", path)\n    dl.get(\"10-K\", \"GOOG\", limit=2)\n# all files are now deleted and only stored in memory\n\nfor path, content in storage.get_file_contents():\n    print(f\"Path: {path}\\nContent [len={len(content)}]: {content[:30]}...\\n\")\n```\n\n    ('Path: sec-edgar-filings/GOOG/10-K/0001652044-25-000014/full-submission.txt\\n'\n     'Content [len=14773739]: \u003cSEC-DOCUMENT\u003e0001652044-25-00...\\n')\n    ('Path: sec-edgar-filings/GOOG/10-K/0001652044-24-000022/full-submission.txt\\n'\n     'Content [len=13927595]: \u003cSEC-DOCUMENT\u003e0001652044-24-00...\\n')\n\n``` python\nfrom sec_downloader import Downloader\ndl = Downloader(\"MyCompanyName\", \"my.email@domain.com\")\nmetadata = dl.get_filing_metadatas(\"https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/0001193125-10-034401-index.htm\", include_amends=True)\nmetadata\n```\n\n    [FilingMetadata(accession_number='0000002488-25-000009', form_type='8-K', primary_doc_url='https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/amd-20250204.htm', items='2.02,7.01,9.01', primary_doc_description='8-K', filing_date='2025-02-04', report_date='2025-02-04', cik='0000002488', company_name='ADVANCED MICRO DEVICES INC', tickers=[Ticker(symbol='AMD', exchange='Nasdaq')])]\n\n# Frequently Asked Questions (FAQ)\n\n**Q: I’m encountering a ValueError stating ‘8-K/A’ forms are not\nsupported. How can I download “8-K/A” filings?**\n\n**A:** To download amended filings such as “8-K/A”, you need to set the\nparameter `include_amends=True`. For example, to download [this\nfiling](https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/0001193125-10-034401-index.htm),\nyou would use:\n\n``` python\nfrom sec_downloader import Downloader\ndl = Downloader(\"MyCompanyName\", \"my.email@domain.com\")\nstr_cik = \"0000002488\"\nstr_acc = \"0001193125-10-034401\"\nmetadata = dl.get_filing_metadatas(f\"{str_cik}/{str_acc}\", include_amends=True)\nmetadata\n```\n\n    [FilingMetadata(accession_number='0001193125-10-034401', form_type='8-K', primary_doc_url='https://www.sec.gov/Archives/edgar/data/2488/000119312510034401/d8ka.htm', items='5.02', primary_doc_description='FORM 8-K/A', filing_date='2010-02-19', report_date='2010-02-16', cik='0000002488', company_name='ADVANCED MICRO DEVICES INC', tickers=[Ticker(symbol='AMD', exchange='Nasdaq')])]\n\n# Contributing\n\nFollow these steps to install the project locally for development:\n\n1.  Install the project with the command `pip install -e \".[dev]\"`.\n\n\u003e **Note** We highly recommend using virtual environments for Python\n\u003e development. If you’d like to use virtual environments, follow these\n\u003e steps instead:\n\u003e\n\u003e - Create a virtual environment `python3 -m venv .venv`\n\u003e - Activate the virtual environment `source .venv/bin/activate`\n\u003e - Install the project with the command `pip install -e \".[dev]\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijas%2Fsec-downloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felijas%2Fsec-downloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijas%2Fsec-downloader/lists"}