<!-- align a paragraph to the center -->
<p align="center">
<a href="https://github.com/dgunning/edgartools">
<img src="https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/edgartools-logo.png" alt="edgar-tools-logo" height="80">
</a>
</p>
<p align="center">The world's easiest, most powerful edgar library</p>
[](https://pypi.org/project/edgartools)
[](https://www.codefactor.io/repository/github/dgunning/edgartools)
[](https://github.com/pypa/hatch)
-----
<p align="center">
<a href="https://github.com/dgunning/edgartools">
<img src="docs/images/edgartools-demo.gif" alt="edgardemo" height="500">
</a>
</p>
# Why edgartools?
📊 Access company financials, insider trades, and SEC filings instantly with Python's most powerful EDGAR data library. 🚀 Easy to use, fast results.
# Features
- 📁 **Access any SEC filing**: You can access any SEC filing since 1994.
- 💰 **Company Financials**: Comprehensive company financials from 10-K and 10-Q filings
- 👤 **Insider Transactions**: Search for and get insider transactions
- 📅 **List filings for any date range**: List filings for **year, quarter** e.g. or date range `2024-02-29:2024-03-15`
- 🌟 **Best looking edgar library**: Uses **[rich](https://rich.readthedocs.io/en/stable/introduction.html)** library to display SEC Edgar data in a beautiful way.
- 🧠 **Intuitive and easy to use**: **edgartools** has a super simple API that is easy to use.
- ��️ **Works as a library or a CLI**: You can use edgartools as a library in your code or as a CLI tool.
- 🔄 **Page through filings**: Use `filings.next()` and `filings.previous()` to page through filings
- 🏗️ **Build Data Pipelines**: Build data pipelines by finding, filtering, transforming and saving filings
- ✅ **Select a filing**: You can select a filing from the list of filings.
- 📄 **View the filing as HTML or text**: Find a filing then get the content as HTML or text.
- 🔢 **Chunk filing text**: You can chunk the filing text into sections for vector embedding.
- 🔍 **Preview the filing**: You can preview the filing in the terminal or a notebook.
- 🔎 **Search through a filing**: You can search through a filing for a keyword.
- 📊 **Parse XBRL**: Extract XBRL data into intuitive data structures.
- 💾 **Data Objects**: Automatically downloads and parses filings into data objects.
- 📥 **Download any attachment**: You can download any attachment from the filing.
- 🕒 **Automatic throttling**: Automatically throttles requests to Edgar to avoid being blocked.
- 📥 **Bulk downloads**: Faster batch processing through bulk downloads of filings and facts
- 🔢 **Get company by Ticker or Cik**: Get a company by ticker `Company("SNOW")` or cik `Company(1640147)`
- **Get company filings**: You can get all the company's historical filings using `company.get_filings()`
- 📈 **Get company facts**: You can get company facts using `company.get_facts()`
- 🔍 **Lookup Ticker by CUSIP**: You can lookup a ticker by CUSIP
- 📑 **Dataset of SEC entities**: You can get a dataset of SEC companies and persons
- 📈 **Fund Reports**: Search for and get 13F-HR fund reports
- 🛠️ **Works as a library or a CLI**: You can use edgartools as a library in your code or as a CLI tool.
# Getting started
Install using pip
```bash
pip install edgartools
```
Import and start using
```python
from edgar import *
# Tell the SEC who you are
set_identity("Michael Mccallum mike.mccalum@indigo.com")
filings = get_filings()
```
# Key Concepts
## Getting financials
```python
c = Company("AAPL")
# Get the latest 10-Q filing
filing = c.latest("10-Q")
# Convert to a data object, in this case a TenQ object
tenq = filing.obj()
# Get the financials
financials = tenq.financials
```
## Listing filings
```python
filings = get_filings(form=['10-K', '10-Q'], year=2020)
filing = filings[0]
```
## Finding things
```python
filing = find("0001065280-23-000273")
```
For a deeper dive see **[Finding things with edgartools](https://github.com/dgunning/edgartools/wiki/FindingThings)**
# How to use edgartools
| | Code |
|--------------------------------------|-------------------------------------------------------|
| Set your EDGAR identity in Linux/Mac | `export EDGAR_IDENTITY="email@domain.com"` |
| Set your EDGAR identity in Windows | `set EDGAR_IDENTITY="email@domain.com"` |
| Set identity in Windows Powershell | `$env:EDGAR_IDENTITY="email@domain.com"` |
| Set identity in Python | `set_identity("email@domain.com")` |
| Importing the library | `from edgar import *` |
### Working with filings 📁
#### 🔍 Getting Filings
| | Code |
|----------------------------------------|-------------------------------------------------|
| 📅 Get filings for the year to date | `filings = get_filings()` |
| 📊 Get only XBRL filings | `filings = get_filings(index="xbrl")` |
| 📆 Get filings for a specific year | `filings = get_filings(2020)` |
| 🗓️ Get filings for a specific quarter | `filings = get_filings(2020, 1)` |
| 📚 Get filings for multiple years | `filings = get_filings([2020, 2021])` |
| 📈 Get filings for a range of years | `filings = get_filings(year=range(2010, 2020))` |
| 📈 Get filings released just now | `filings = get_latest_filings()` |
#### 📄 Filtering Filings
| | Code |
|-----------------------------------|------------------------------------------------------------------|
| 📝 Filter by form type | `filings.filter(form="10-K")` |
| 📑 Filter by multiple forms | `filings.filter(form=["10-K", "10-Q"])` |
| 🔄 Include form amendments | `filings.filter(form="10-K", amendments=True)` |
| 🏢 Filter by CIK | `filings.filter(cik="0000320193")` |
| 🏙️ Filter by multiple CIKs | `filings.filter(cik=["0000320193", "1018724"])` |
| 🏷️ Filter by ticker | `filings.filter(ticker="AAPL")` |
| 🏷️🏷️ Filter by multiple tickers | `filings.filter(ticker=["AAPL", "MSFT"])` |
| 📅 Filter on a specific date | `filings.filter(date="2020-01-01")` |
| 📅↔️📅 Filter between dates | `filings.filter(date="2020-01-01:2020-03-01")` |
| 📅⬅️ Filter before a date | `filings.filter(date=":2020-03-01")` |
| 📅➡️ Filter after a date | `filings.filter(date="2020-03-01:")` |
| 🔀 Combine multiple filters | `filings.filter(form="10-K", date="2020-01-01:", ticker="AAPL")` |
#### 📊 Viewing and Manipulating Filings
| | Code |
|--------------------------------------|--------------------------|
| ⏭️ Show the next page of filings | `filings.next()` |
| ⏮️ Show the previous page of filings | `filings.prev()` |
| 🔝 Get the first n filings | `filings.head(20)` |
| 🔚 Get the last n filings | `filings.tail(20)` |
| 🕒 Get the latest n filings by date | `filings.latest(20)` |
| 🎲 Get a random sample of filings | `filings.sample(20)` |
| 🐼 Get filings as a pandas dataframe | `filings.to_pandas()` |
### Working with a filing 📄
#### 🔍 Accessing and viewing a Filing
| | Code |
|-------------------------------------|-----------------------------------------------------------|
| 📌 Get a single filing | `filing = filings[3]` |
| 🔢 Get a filing by accession number | `filing = get_by_accession_number("0000320193-20-34576")` |
| 🏠 Get the filing homepage | `filing.homepage` |
| 🌐 Open a filing in the browser | `filing.open()` |
| 🏠 Open homepage in the browser | `filing.homepage.open()` |
| 💻 View the filing in the terminal | `filing.view()` |
#### 📊 Extracting Filing Content
| | Code |
|-------------------------------------|-----------------------------|
| 🌐 Get the HTML of the filing | `filing.html()` |
| 📊 Get the XBRL of the filing | `filing.xbrl()` |
| 📝 Get the filing as markdown | `filing.markdown()` |
| 📄 Get the full submission text | `filing.full_text_submission()` |
| 🔢 Get and parse filing data object | `filing.obj()` |
| 📑 Get filing header | `filing.header` |
#### 🔎 Searching inside a Filing
| | Code |
|-----------------------------|----------------------------------------|
| 🔍 Search within the filing | `filing.search("query")` |
| 🔍 Search with regex | `filing.search("pattern", regex=True)` |
| 📊 Get filing sections | `filing.sections()` |
#### 📎 Working with Attachments
| | Code |
|-------------------------------|-----------------------------------|
| 📁 Get all filing attachments | `filing.attachments` |
| 📄 Get a single attachment | `attachment = filing.attachments[0]` |
| 🌐 Open attachment in browser | `attachment.open()` |
| ⬇️ Download an attachment | `content = attachment.download()` |
### Working with a company
| | Code |
|------------------------------------------|---------------------------------------------------------------|
| Get a company by ticker | `company = Company("AAPL")` |
| Get a company by CIK | `company = Company("0000320193")` |
| Get company facts | `company.get_facts()` |
| Get company facts as a pandas dataframe | `company.get_facts().to_pandas()` |
| Get company filings | `company.get_filings()` |
| Get company filings by form | `company.get_filings(form="10-K")` |
| Get the latest 10-Q | `company.latest("10-Q")` |
| Get the last 5 10-Q's | `company.get_filings(form="10-Q", 5)` |
| Get a company filing by accession_number | `company.get_filing(accession_number="0000320193-21-000139")` |
| Get the company's financials | `company.financials` |
| Get the company's balance sheet | `company.financials.get_balance_sheet` |
| Get the company's income statement | `company.financials.get_income_statement` |
| Get the company's cash flow statement | `company.financials.get_cash_flow_statement` |
# Installation
```console
pip install edgartools
```
# Usage
## Set your Edgar user identity
Before you can access the SEC Edgar API you need to set the identity that you will use to access Edgar.
This is usually your name and email, or a company name and email but you can also just use an email.
```bash
Sample Company Name AdminContact@<sample company domain>.com
```
The user identity is sent in the User-Agent string and the Edgar API will refuse to respond to your request without it.
EdgarTools will look for an environment variable called `EDGAR_IDENTITY` and use that in each request.
So, you need to set this environment variable before using it.
### Setting EDGAR_IDENTITY in Linux/Mac
```bash
export EDGAR_IDENTITY="mcalum@gmail.com"
```
### Setting EDGAR_IDENTITY in Windows Powershell
```bash
$Env:EDGAR_IDENTITY="mcalum@gmail.com"
```
Alternatively, you can call `set_identity` which does the same thing.
```python
from edgar import set_identity
set_identity("mcalum@gmail.com")
```
For more detail see https://www.sec.gov/os/accessing-edgar-data
## Usage
### Importing edgar
```python
from edgar import *
```
## [Using the Filing API](https://github.com/dgunning/edgartools/wiki/WorkingWithFilings)
Use the Filing API when you are not working with a specific company, but want to get a list of filings.
For details on how to use the Filing API see **[Using the Filing API](https://github.com/dgunning/edgartools/wiki/WorkingWithFilings)**
## [Using the Company API](https://github.com/dgunning/edgartools/wiki/WorkingWithCompanies)
You can use the company ticker or CIK to get a company.
```python
c = Company("AAPL") # or Company("0000320193") or Company(320193)
```
With the Company API you can find a company by ticker or CIK, and get the company's filings, facts and financials.
```python
Company("AAPL")
.latest("10-Q")
.obj()
```
See **[Using the Company API](https://github.com/dgunning/edgartools/wiki/WorkingWithCompanies)**
## Viewing and downloading attachments
Every filing has a list of attachments. You can view the attachments using `filing.attachments`
```python
# View the attachments
filing.attachments
```
You can access each attachment using the bracket operator `[]` and the index of the attachment.
```python
# Get the first attachment
attachment = filing.attachments[0]
```
You can download the attachment using `attachment.download()`. This will download the attachment to string or bytes in memory.
## Data Objects
Now the reason you may want to download attachments is to get information contained in data files.
For example, **13F-HR** filings have attached infotable.xml files containing data from the holding report for that filing.
Fortunately, the library handles this for you. If you call `filing.obj()` it will automatically download and parse the data files
into a data object, for several different form types. Currently, the following forms are supported:
| Form | Data Object | Description |
|----------------------------|------------------------------|---------------------------------------|
| 10-K | `TenK` | Annual report |
| 10-Q | `TenQ` | Quarterly report |
| 8-K | `EightK` | Current report |
| MA-I | `MunicipalAdvisorForm` | Municipal advisor initial filing |
| Form 144 | `Form144` | Notice of proposed sale of securities |
| C, C-U, C-AR, C-TR | `FormC` | Form C Crowdfunding Offering |
| D | `FormD` | Form D Offering |
| 3,4,5 | `Ownership` | Ownership reports |
| 13F-HR | `ThirteenF` | 13F Holdings Report |
| NPORT-P | `FundReport` | Fund Report |
| EFFECT | `Effect` | Notice of Effectiveness |
| Any other filing with XBRL | `XBRLData` or `XBRLInstance` | Container for XBRL data |
For example, to get the data object for a **13F-HR** filing you can do the following:
```python
filings = get_filings(form="13F-HR")
filing = filings[0]
thirteenf = filing.obj()
```
If you call `obj()` on a filing that does not have a data file, then it will return `None`.
## Working with XBRL filings
Some filings are in **XBRL (eXtensible Business Markup Language)** format.
These are mainly the newer filings, as the SEC has started requiring this for newer filings.
If a filing is in XBRL format then it opens up a lot more ways to get structured data about that specific filing and also
about the company referred to in that filing.
The `Filing` class has an `xbrl` function that will download, parse and structure the filing's XBRL document if one exists.
If it does not exist, then `filing.xbrl()` will return `None`.
The function `filing.xbrl()` returns an `XBRLData` instance if the XBRL files contain presentation information or `XBRLInstance` if it a simple instance document with just the facts.
For more details see **[Parsing XBRL](https://github.com/dgunning/edgartools/wiki/ParsingXBRL)**
```python
filing_xbrl = filing.xbrl()
```
## Financials
Some filings, notably **10-K** and **10-Q** filings contain financial statements in XBRL format.
You can get the financials from the XBRL data using the `Financials` class.
The Company object has a `financials` property that will return the financials for the company.
```python
from edgar.financials import Financials
company = Company("AAPL")
financials = company.financials
```
You can also get the financials through the `Tenk` and `TenQ` data objects.
Here is an example that gets the latest Apple financials
```python
tenk = Company("AAPL").get_filings(form="10-K").latest(1).obj()
financials = tenk.financials
financials.get_balance_sheet() # or financials.balance_sheet
financials.get_income_statement() # or financials.income
financials.get_cash_flow_statement() # or financials.cashflow
financials.get_statement_of_changes_in_equity() # or financials.equity
financials.get_statement_of_comprehensive_income() # or financials.comprehensive_income
```
### Get the financial data as a pandas dataframe
Each of the financial statements - `BalanceSheet`, `IncomeStatement` and `CashFlowStatement` - have a `get_dataframe()` method that will return the data as a pandas dataframe.
```python
balance_sheet_df = financials.get_balance_sheet().get_dataframe()
```
## TenK (10-K) Data Object
For 10-K filngs the 10-K Data Object allows you to access almost any data related to the filing - both text and financial data.
```python
c = Company("ORCL")
filing = c.get_filings(form="10-K").latest()
tenk = filing.obj()
```
You can also get it directly using the property `latest_tenk` on the `Company` object.
```python
c = Company("ORCL")
c.latest_tenk
```
### Getting 10-K Items
You can get the text of individual sections of the 10-K filing using tge bracket `[]` operator.
```python
tenk['Item 1']
```
There are also a few convenience methods to get the most common sections.
```python
# Get Item 1 - Business
tenk.business
# Get Item 1A - Risk Factors
tenk.risk_factors
# Get Item 7 - Management's Discussion and Analysis
tenk.management_discussion
# Get Item 10 - Directors, Officers and Corporate Governance
tenk.directors_officers_and_governance
```
## Downloading Edgar Data
The library is designed to make real time calls to EDGAR to get the latest data. However, you may want to download data for offline use or to build a dataset.
### Download Bulk Company Data
You can download all the company **filings** and **facts** from Edgar using the `download_edgar_data` function.
Note that this will store json files for each company of their facts and submissions, but it will not include the actual HTML or other attachments.
It will however dramatically speed up loading companies by cik or ticker.
The submissions and facts bulk data files are each over 1.GB in size, and take around a few minutes each.
The data is stored by default in the `~/.edgar` directory. You can change this by setting the `EDGAR_LOCAL_DATA_DIR` environment variable.
```python
def download_edgar_data(submissions: bool = True, facts: bool = True, reference: bool = True):
"""
Download all the company data from Edgar
:param submissions: Download all the company submissions
:param facts: Download all the company facts
:param reference: Download reference data
"""
download_edgar_data()
```
### Using Bulk Data
If you want edgartools to use the bulk data files you can call `use_local_storage()` before you start making calls using the library.
Alternatively, set `EDGAR_USE_LOCAL_DATA` to `True` in your environment.
### Downsides of using bulk data
- The filings downloaded for each company is limited to the last 1000
- You will need to download the latest data every so often to keep it up to date.
## Downloading Attachments
You can download attachments from a filing using the `download` method on the attachments. This will download all the attached files to a folder of your choice.
```python
class Attachments:
def download(self, path: Union[str, Path], archive: bool = False):
"""
Download all the attachments to a specified path.
If the path is a directory, the file is saved with its original name in that directory.
If the path is a file, the file is saved with the given path name.
If archive is True, the attachments are saved in a zip file.
path: str or Path - The path to save the attachments
archive: bool (default False) - If True, save the attachments in a zip file
"""
...
# Usage
filing.attachments.download(path)
```
# Contributing
Contributions are welcome! We would love to hear your thoughts on how this library could be better at working with SEC Edgar.
## Reporting Issues
We use GitHub issues to track public bugs.
Report a bug by [opening a new issue](https://github.com/dgunning/edgartools/issues); it's that easy!
## Making code changes
- Fork the repo and create your branch from master.
- If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Ensure the test suite passes.
- Make sure your code lints.
- Issue that pull request!
# License
`edgartools` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
## Contact
- **[Project Documentation](https://dgunning.github.io/edgartools/)**
- **[Edgartools Blog](https://www.edgartools.io)**
- **[Dwight Gunning on LinkedIn](https://www.linkedin.com/in/dwight-gunning-860124/)**
## Star History
[](https://star-history.com/#dgunning/edgartools&Timeline)
Raw data
{
"_id": null,
"home_page": null,
"name": "edgartools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "company, edgar, filings, finance, financial, python, reports, sec",
"author": null,
"author_email": "Dwight Gunning <dgunning@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/51/d7/84d477596ed9621b073cf49b22e93327456a53b8f64a4851a6a636c94a1a/edgartools-3.8.4.tar.gz",
"platform": null,
"description": "<!-- align a paragraph to the center -->\n<p align=\"center\">\n<a href=\"https://github.com/dgunning/edgartools\">\n <img src=\"https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/edgartools-logo.png\" alt=\"edgar-tools-logo\" height=\"80\">\n</a>\n</p>\n<p align=\"center\">The world's easiest, most powerful edgar library</p>\n\n[](https://pypi.org/project/edgartools)\n\n\n[](https://www.codefactor.io/repository/github/dgunning/edgartools)\n[](https://github.com/pypa/hatch)\n\n-----\n\n<p align=\"center\">\n<a href=\"https://github.com/dgunning/edgartools\">\n <img src=\"docs/images/edgartools-demo.gif\" alt=\"edgardemo\" height=\"500\">\n</a>\n</p>\n\n# Why edgartools?\n\ud83d\udcca Access company financials, insider trades, and SEC filings instantly with Python's most powerful EDGAR data library. \ud83d\ude80 Easy to use, fast results.\n\n# Features\n- \ud83d\udcc1 **Access any SEC filing**: You can access any SEC filing since 1994.\n- \ud83d\udcb0 **Company Financials**: Comprehensive company financials from 10-K and 10-Q filings\n- \ud83d\udc64 **Insider Transactions**: Search for and get insider transactions\n- \ud83d\udcc5 **List filings for any date range**: List filings for **year, quarter** e.g. or date range `2024-02-29:2024-03-15`\n- \ud83c\udf1f **Best looking edgar library**: Uses **[rich](https://rich.readthedocs.io/en/stable/introduction.html)** library to display SEC Edgar data in a beautiful way.\n- \ud83e\udde0 **Intuitive and easy to use**: **edgartools** has a super simple API that is easy to use.\n- \ufffd\ufffd\ufe0f **Works as a library or a CLI**: You can use edgartools as a library in your code or as a CLI tool.\n- \ud83d\udd04 **Page through filings**: Use `filings.next()` and `filings.previous()` to page through filings\n- \ud83c\udfd7\ufe0f **Build Data Pipelines**: Build data pipelines by finding, filtering, transforming and saving filings\n- \u2705 **Select a filing**: You can select a filing from the list of filings.\n- \ud83d\udcc4 **View the filing as HTML or text**: Find a filing then get the content as HTML or text.\n- \ud83d\udd22 **Chunk filing text**: You can chunk the filing text into sections for vector embedding.\n- \ud83d\udd0d **Preview the filing**: You can preview the filing in the terminal or a notebook.\n- \ud83d\udd0e **Search through a filing**: You can search through a filing for a keyword.\n- \ud83d\udcca **Parse XBRL**: Extract XBRL data into intuitive data structures.\n- \ud83d\udcbe **Data Objects**: Automatically downloads and parses filings into data objects.\n- \ud83d\udce5 **Download any attachment**: You can download any attachment from the filing.\n- \ud83d\udd52 **Automatic throttling**: Automatically throttles requests to Edgar to avoid being blocked.\n- \ud83d\udce5 **Bulk downloads**: Faster batch processing through bulk downloads of filings and facts\n- \ud83d\udd22 **Get company by Ticker or Cik**: Get a company by ticker `Company(\"SNOW\")` or cik `Company(1640147)`\n- **Get company filings**: You can get all the company's historical filings using `company.get_filings()`\n- \ud83d\udcc8 **Get company facts**: You can get company facts using `company.get_facts()`\n- \ud83d\udd0d **Lookup Ticker by CUSIP**: You can lookup a ticker by CUSIP\n- \ud83d\udcd1 **Dataset of SEC entities**: You can get a dataset of SEC companies and persons\n- \ud83d\udcc8 **Fund Reports**: Search for and get 13F-HR fund reports\n- \ud83d\udee0\ufe0f **Works as a library or a CLI**: You can use edgartools as a library in your code or as a CLI tool.\n\n\n# Getting started\n\nInstall using pip\n```bash\npip install edgartools\n```\n\nImport and start using\n```python\nfrom edgar import *\n\n# Tell the SEC who you are\nset_identity(\"Michael Mccallum mike.mccalum@indigo.com\")\n\nfilings = get_filings()\n```\n\n\n\n# Key Concepts\n\n## Getting financials\n```python\nc = Company(\"AAPL\")\n# Get the latest 10-Q filing\n\nfiling = c.latest(\"10-Q\")\n\n# Convert to a data object, in this case a TenQ object\ntenq = filing.obj()\n\n# Get the financials\nfinancials = tenq.financials\n```\n\n## Listing filings\n\n```python\nfilings = get_filings(form=['10-K', '10-Q'], year=2020)\nfiling = filings[0]\n```\n\n## Finding things\n\n```python\nfiling = find(\"0001065280-23-000273\")\n```\nFor a deeper dive see **[Finding things with edgartools](https://github.com/dgunning/edgartools/wiki/FindingThings)**\n\n\n# How to use edgartools\n\n| | Code |\n|--------------------------------------|-------------------------------------------------------|\n| Set your EDGAR identity in Linux/Mac | `export EDGAR_IDENTITY=\"email@domain.com\"` |\n| Set your EDGAR identity in Windows | `set EDGAR_IDENTITY=\"email@domain.com\"` |\n| Set identity in Windows Powershell | `$env:EDGAR_IDENTITY=\"email@domain.com\"` |\n| Set identity in Python | `set_identity(\"email@domain.com\")` |\n| Importing the library | `from edgar import *` |\n\n### Working with filings \ud83d\udcc1\n\n#### \ud83d\udd0d Getting Filings\n\n| | Code |\n|----------------------------------------|-------------------------------------------------|\n| \ud83d\udcc5 Get filings for the year to date | `filings = get_filings()` |\n| \ud83d\udcca Get only XBRL filings | `filings = get_filings(index=\"xbrl\")` |\n| \ud83d\udcc6 Get filings for a specific year | `filings = get_filings(2020)` |\n| \ud83d\uddd3\ufe0f Get filings for a specific quarter | `filings = get_filings(2020, 1)` |\n| \ud83d\udcda Get filings for multiple years | `filings = get_filings([2020, 2021])` |\n| \ud83d\udcc8 Get filings for a range of years | `filings = get_filings(year=range(2010, 2020))` |\n| \ud83d\udcc8 Get filings released just now | `filings = get_latest_filings()` |\n\n#### \ud83d\udcc4 Filtering Filings\n\n| | Code |\n|-----------------------------------|------------------------------------------------------------------|\n| \ud83d\udcdd Filter by form type | `filings.filter(form=\"10-K\")` |\n| \ud83d\udcd1 Filter by multiple forms | `filings.filter(form=[\"10-K\", \"10-Q\"])` |\n| \ud83d\udd04 Include form amendments | `filings.filter(form=\"10-K\", amendments=True)` |\n| \ud83c\udfe2 Filter by CIK | `filings.filter(cik=\"0000320193\")` |\n| \ud83c\udfd9\ufe0f Filter by multiple CIKs | `filings.filter(cik=[\"0000320193\", \"1018724\"])` |\n| \ud83c\udff7\ufe0f Filter by ticker | `filings.filter(ticker=\"AAPL\")` |\n| \ud83c\udff7\ufe0f\ud83c\udff7\ufe0f Filter by multiple tickers | `filings.filter(ticker=[\"AAPL\", \"MSFT\"])` |\n| \ud83d\udcc5 Filter on a specific date | `filings.filter(date=\"2020-01-01\")` |\n| \ud83d\udcc5\u2194\ufe0f\ud83d\udcc5 Filter between dates | `filings.filter(date=\"2020-01-01:2020-03-01\")` |\n| \ud83d\udcc5\u2b05\ufe0f Filter before a date | `filings.filter(date=\":2020-03-01\")` |\n| \ud83d\udcc5\u27a1\ufe0f Filter after a date | `filings.filter(date=\"2020-03-01:\")` |\n| \ud83d\udd00 Combine multiple filters | `filings.filter(form=\"10-K\", date=\"2020-01-01:\", ticker=\"AAPL\")` |\n\n#### \ud83d\udcca Viewing and Manipulating Filings\n\n| | Code |\n|--------------------------------------|--------------------------|\n| \u23ed\ufe0f Show the next page of filings | `filings.next()` |\n| \u23ee\ufe0f Show the previous page of filings | `filings.prev()` |\n| \ud83d\udd1d Get the first n filings | `filings.head(20)` |\n| \ud83d\udd1a Get the last n filings | `filings.tail(20)` |\n| \ud83d\udd52 Get the latest n filings by date | `filings.latest(20)` |\n| \ud83c\udfb2 Get a random sample of filings | `filings.sample(20)` |\n| \ud83d\udc3c Get filings as a pandas dataframe | `filings.to_pandas()` |\n\n### Working with a filing \ud83d\udcc4\n\n#### \ud83d\udd0d Accessing and viewing a Filing\n\n| | Code |\n|-------------------------------------|-----------------------------------------------------------|\n| \ud83d\udccc Get a single filing | `filing = filings[3]` |\n| \ud83d\udd22 Get a filing by accession number | `filing = get_by_accession_number(\"0000320193-20-34576\")` |\n| \ud83c\udfe0 Get the filing homepage | `filing.homepage` |\n| \ud83c\udf10 Open a filing in the browser | `filing.open()` |\n| \ud83c\udfe0 Open homepage in the browser | `filing.homepage.open()` |\n| \ud83d\udcbb View the filing in the terminal | `filing.view()` |\n\n#### \ud83d\udcca Extracting Filing Content\n\n| | Code |\n|-------------------------------------|-----------------------------|\n| \ud83c\udf10 Get the HTML of the filing | `filing.html()` |\n| \ud83d\udcca Get the XBRL of the filing | `filing.xbrl()` |\n| \ud83d\udcdd Get the filing as markdown | `filing.markdown()` |\n| \ud83d\udcc4 Get the full submission text | `filing.full_text_submission()` |\n| \ud83d\udd22 Get and parse filing data object | `filing.obj()` |\n| \ud83d\udcd1 Get filing header | `filing.header` |\n\n#### \ud83d\udd0e Searching inside a Filing\n\n| | Code |\n|-----------------------------|----------------------------------------|\n| \ud83d\udd0d Search within the filing | `filing.search(\"query\")` |\n| \ud83d\udd0d Search with regex | `filing.search(\"pattern\", regex=True)` |\n| \ud83d\udcca Get filing sections | `filing.sections()` |\n\n#### \ud83d\udcce Working with Attachments\n\n| | Code |\n|-------------------------------|-----------------------------------|\n| \ud83d\udcc1 Get all filing attachments | `filing.attachments` |\n| \ud83d\udcc4 Get a single attachment | `attachment = filing.attachments[0]` |\n| \ud83c\udf10 Open attachment in browser | `attachment.open()` |\n| \u2b07\ufe0f Download an attachment | `content = attachment.download()` |\n\n### Working with a company\n\n| | Code |\n|------------------------------------------|---------------------------------------------------------------|\n| Get a company by ticker | `company = Company(\"AAPL\")` |\n| Get a company by CIK | `company = Company(\"0000320193\")` |\n| Get company facts | `company.get_facts()` |\n| Get company facts as a pandas dataframe | `company.get_facts().to_pandas()` |\n| Get company filings | `company.get_filings()` |\n| Get company filings by form | `company.get_filings(form=\"10-K\")` |\n| Get the latest 10-Q | `company.latest(\"10-Q\")` |\n| Get the last 5 10-Q's | `company.get_filings(form=\"10-Q\", 5)` |\n| Get a company filing by accession_number | `company.get_filing(accession_number=\"0000320193-21-000139\")` |\n| Get the company's financials | `company.financials` |\n| Get the company's balance sheet | `company.financials.get_balance_sheet` |\n| Get the company's income statement | `company.financials.get_income_statement` |\n| Get the company's cash flow statement | `company.financials.get_cash_flow_statement` |\n\n# Installation\n\n```console\npip install edgartools\n```\n\n# Usage\n\n\n## Set your Edgar user identity\n\nBefore you can access the SEC Edgar API you need to set the identity that you will use to access Edgar.\nThis is usually your name and email, or a company name and email but you can also just use an email.\n```bash\nSample Company Name AdminContact@<sample company domain>.com\n```\n\nThe user identity is sent in the User-Agent string and the Edgar API will refuse to respond to your request without it.\n\nEdgarTools will look for an environment variable called `EDGAR_IDENTITY` and use that in each request.\nSo, you need to set this environment variable before using it.\n\n### Setting EDGAR_IDENTITY in Linux/Mac\n```bash\nexport EDGAR_IDENTITY=\"mcalum@gmail.com\"\n```\n\n### Setting EDGAR_IDENTITY in Windows Powershell\n```bash\n $Env:EDGAR_IDENTITY=\"mcalum@gmail.com\"\n```\nAlternatively, you can call `set_identity` which does the same thing.\n\n```python\nfrom edgar import set_identity\nset_identity(\"mcalum@gmail.com\")\n```\nFor more detail see https://www.sec.gov/os/accessing-edgar-data\n\n## Usage\n\n### Importing edgar\n\n```python\nfrom edgar import *\n```\n\n## [Using the Filing API](https://github.com/dgunning/edgartools/wiki/WorkingWithFilings)\nUse the Filing API when you are not working with a specific company, but want to get a list of filings.\n\nFor details on how to use the Filing API see **[Using the Filing API](https://github.com/dgunning/edgartools/wiki/WorkingWithFilings)**\n\n## [Using the Company API](https://github.com/dgunning/edgartools/wiki/WorkingWithCompanies)\n\nYou can use the company ticker or CIK to get a company.\n\n```python\nc = Company(\"AAPL\") # or Company(\"0000320193\") or Company(320193)\n```\n\n\nWith the Company API you can find a company by ticker or CIK, and get the company's filings, facts and financials.\n\n```python\nCompany(\"AAPL\")\n .latest(\"10-Q\")\n .obj()\n```\n\n\n\nSee **[Using the Company API](https://github.com/dgunning/edgartools/wiki/WorkingWithCompanies)**\n\n## Viewing and downloading attachments\n\nEvery filing has a list of attachments. You can view the attachments using `filing.attachments`\n\n```python\n# View the attachments\nfiling.attachments\n```\n\n\n\nYou can access each attachment using the bracket operator `[]` and the index of the attachment.\n \n```python\n# Get the first attachment\nattachment = filing.attachments[0]\n```\n\n\n\nYou can download the attachment using `attachment.download()`. This will download the attachment to string or bytes in memory. \n\n## Data Objects\n\nNow the reason you may want to download attachments is to get information contained in data files.\nFor example, **13F-HR** filings have attached infotable.xml files containing data from the holding report for that filing.\n\nFortunately, the library handles this for you. If you call `filing.obj()` it will automatically download and parse the data files\ninto a data object, for several different form types. Currently, the following forms are supported:\n\n| Form | Data Object | Description |\n|----------------------------|------------------------------|---------------------------------------|\n| 10-K | `TenK` | Annual report |\n| 10-Q | `TenQ` | Quarterly report |\n| 8-K | `EightK` | Current report |\n| MA-I | `MunicipalAdvisorForm` | Municipal advisor initial filing |\n| Form 144 | `Form144` | Notice of proposed sale of securities |\n| C, C-U, C-AR, C-TR | `FormC` | Form C Crowdfunding Offering |\n| D | `FormD` | Form D Offering |\n| 3,4,5 | `Ownership` | Ownership reports |\n| 13F-HR | `ThirteenF` | 13F Holdings Report |\n| NPORT-P | `FundReport` | Fund Report |\n| EFFECT | `Effect` | Notice of Effectiveness |\n| Any other filing with XBRL | `XBRLData` or `XBRLInstance` | Container for XBRL data |\n\nFor example, to get the data object for a **13F-HR** filing you can do the following:\n\n```python\nfilings = get_filings(form=\"13F-HR\")\nfiling = filings[0]\nthirteenf = filing.obj()\n```\n\n\n\nIf you call `obj()` on a filing that does not have a data file, then it will return `None`.\n\n\n## Working with XBRL filings\n\nSome filings are in **XBRL (eXtensible Business Markup Language)** format. \nThese are mainly the newer filings, as the SEC has started requiring this for newer filings.\n\nIf a filing is in XBRL format then it opens up a lot more ways to get structured data about that specific filing and also \nabout the company referred to in that filing.\n\nThe `Filing` class has an `xbrl` function that will download, parse and structure the filing's XBRL document if one exists.\nIf it does not exist, then `filing.xbrl()` will return `None`.\n\nThe function `filing.xbrl()` returns an `XBRLData` instance if the XBRL files contain presentation information or `XBRLInstance` if it a simple instance document with just the facts.\nFor more details see **[Parsing XBRL](https://github.com/dgunning/edgartools/wiki/ParsingXBRL)**\n\n```python\nfiling_xbrl = filing.xbrl()\n```\n\n\n\n## Financials\n\nSome filings, notably **10-K** and **10-Q** filings contain financial statements in XBRL format. \nYou can get the financials from the XBRL data using the `Financials` class.\n\nThe Company object has a `financials` property that will return the financials for the company.\n```python\nfrom edgar.financials import Financials\n\ncompany = Company(\"AAPL\")\nfinancials = company.financials\n\n```\nYou can also get the financials through the `Tenk` and `TenQ` data objects.\n\nHere is an example that gets the latest Apple financials\n\n```python\ntenk = Company(\"AAPL\").get_filings(form=\"10-K\").latest(1).obj()\n\nfinancials = tenk.financials\n\nfinancials.get_balance_sheet() # or financials.balance_sheet\nfinancials.get_income_statement() # or financials.income\nfinancials.get_cash_flow_statement() # or financials.cashflow\nfinancials.get_statement_of_changes_in_equity() # or financials.equity\nfinancials.get_statement_of_comprehensive_income() # or financials.comprehensive_income\n```\n\n\n\n### Get the financial data as a pandas dataframe\n\nEach of the financial statements - `BalanceSheet`, `IncomeStatement` and `CashFlowStatement` - have a `get_dataframe()` method that will return the data as a pandas dataframe.\n\n```python\nbalance_sheet_df = financials.get_balance_sheet().get_dataframe()\n```\n\n\n## TenK (10-K) Data Object\n\nFor 10-K filngs the 10-K Data Object allows you to access almost any data related to the filing - both text and financial data.\n\n```python\nc = Company(\"ORCL\")\nfiling = c.get_filings(form=\"10-K\").latest()\ntenk = filing.obj()\n```\n\nYou can also get it directly using the property `latest_tenk` on the `Company` object.\n\n```python\nc = Company(\"ORCL\")\nc.latest_tenk\n```\n\n\n### Getting 10-K Items\n\nYou can get the text of individual sections of the 10-K filing using tge bracket `[]` operator.\n\n```python\ntenk['Item 1']\n```\n\nThere are also a few convenience methods to get the most common sections.\n\n```python\n# Get Item 1 - Business\ntenk.business\n\n# Get Item 1A - Risk Factors\ntenk.risk_factors\n\n# Get Item 7 - Management's Discussion and Analysis\ntenk.management_discussion\n\n# Get Item 10 - Directors, Officers and Corporate Governance\ntenk.directors_officers_and_governance\n```\n\n\n\n## Downloading Edgar Data\n\nThe library is designed to make real time calls to EDGAR to get the latest data. However, you may want to download data for offline use or to build a dataset.\n\n### Download Bulk Company Data\nYou can download all the company **filings** and **facts** from Edgar using the `download_edgar_data` function.\nNote that this will store json files for each company of their facts and submissions, but it will not include the actual HTML or other attachments.\nIt will however dramatically speed up loading companies by cik or ticker.\n\nThe submissions and facts bulk data files are each over 1.GB in size, and take around a few minutes each.\nThe data is stored by default in the `~/.edgar` directory. You can change this by setting the `EDGAR_LOCAL_DATA_DIR` environment variable.\n\n\n```python\ndef download_edgar_data(submissions: bool = True, facts: bool = True, reference: bool = True):\n \"\"\"\n Download all the company data from Edgar\n :param submissions: Download all the company submissions\n :param facts: Download all the company facts\n :param reference: Download reference data\n \"\"\"\ndownload_edgar_data()\n\n```\n### Using Bulk Data\nIf you want edgartools to use the bulk data files you can call `use_local_storage()` before you start making calls using the library.\nAlternatively, set `EDGAR_USE_LOCAL_DATA` to `True` in your environment.\n\n### Downsides of using bulk data\n- The filings downloaded for each company is limited to the last 1000\n- You will need to download the latest data every so often to keep it up to date.\n\n## Downloading Attachments\n\nYou can download attachments from a filing using the `download` method on the attachments. This will download all the attached files to a folder of your choice.\n\n```python\nclass Attachments:\n \n def download(self, path: Union[str, Path], archive: bool = False):\n \"\"\"\n Download all the attachments to a specified path.\n If the path is a directory, the file is saved with its original name in that directory.\n If the path is a file, the file is saved with the given path name.\n If archive is True, the attachments are saved in a zip file.\n path: str or Path - The path to save the attachments\n archive: bool (default False) - If True, save the attachments in a zip file\n \"\"\" \n ...\n \n# Usage\nfiling.attachments.download(path)\n```\n\n\n# Contributing\n\nContributions are welcome! We would love to hear your thoughts on how this library could be better at working with SEC Edgar.\n\n## Reporting Issues\nWe use GitHub issues to track public bugs. \nReport a bug by [opening a new issue](https://github.com/dgunning/edgartools/issues); it's that easy!\n\n## Making code changes\n- Fork the repo and create your branch from master.\n- If you've added code that should be tested, add tests.\n- If you've changed APIs, update the documentation.\n- Ensure the test suite passes.\n- Make sure your code lints.\n- Issue that pull request!\n\n\n\n# License\n\n`edgartools` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n## Contact\n\n- **[Project Documentation](https://dgunning.github.io/edgartools/)**\n- **[Edgartools Blog](https://www.edgartools.io)**\n- **[Dwight Gunning on LinkedIn](https://www.linkedin.com/in/dwight-gunning-860124/)**\n\n## Star History\n\n[](https://star-history.com/#dgunning/edgartools&Timeline)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Navigate Edgar filings with ease",
"version": "3.8.4",
"project_urls": {
"Documentation": "https://dgunning.github.io/edgartools/",
"Issues": "https://github.com/dgunning/edgartools/issues",
"Source": "https://github.com/dgunning/edgartools"
},
"split_keywords": [
"company",
" edgar",
" filings",
" finance",
" financial",
" python",
" reports",
" sec"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "83a001493b1f055977305a2ee7f6ca6bc451223f445cfb6a8a541280ce348911",
"md5": "e37bb1faa3b6f4c43998004ef7b9b897",
"sha256": "ada95234d402cab7f0d3d6b27a1050bf70e45f356557ddb8b10294f66308acbc"
},
"downloads": -1,
"filename": "edgartools-3.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e37bb1faa3b6f4c43998004ef7b9b897",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 1067939,
"upload_time": "2025-01-19T14:39:45",
"upload_time_iso_8601": "2025-01-19T14:39:45.320407Z",
"url": "https://files.pythonhosted.org/packages/83/a0/01493b1f055977305a2ee7f6ca6bc451223f445cfb6a8a541280ce348911/edgartools-3.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "51d784d477596ed9621b073cf49b22e93327456a53b8f64a4851a6a636c94a1a",
"md5": "ca530b913d8a3297f43dbf0da4b0c64f",
"sha256": "b1fee495c60693a062b50ab13bbb401403a4179248bba78f5956305d259d7001"
},
"downloads": -1,
"filename": "edgartools-3.8.4.tar.gz",
"has_sig": false,
"md5_digest": "ca530b913d8a3297f43dbf0da4b0c64f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1041792,
"upload_time": "2025-01-19T14:39:48",
"upload_time_iso_8601": "2025-01-19T14:39:48.518460Z",
"url": "https://files.pythonhosted.org/packages/51/d7/84d477596ed9621b073cf49b22e93327456a53b8f64a4851a6a636c94a1a/edgartools-3.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-19 14:39:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dgunning",
"github_project": "edgartools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "edgartools"
}
JSON
