Skip to content

Python library for working with SEC Edgar

License

Notifications You must be signed in to change notification settings

poggiolabs/edgartools

 
 

Repository files navigation

edgar-tools-logo

The world's easiest, most powerful edgar library

PyPI - Version GitHub last commit GitHub Workflow Status CodeFactor Hatch project GitHub

edgardemo

Features

  • 🧠 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.
  • 📁 Access any SEC filing: You can access any SEC filing since 1994.
  • 📅 List filings for any date range: You can list filings for any year, quarter e.g. or date range 2024-02-29:2024-03-15
  • 🌟 Best looking edgar library: Uses rich library to display SEC Edgar data in a beautiful way.
  • 🔄 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: If a filing has XBRL, you can parse it to a dataframe.
  • 💾 Data Objects: Automatically downloads and parses filings into data objects.
  • 📥 Download any attachment: You can download any attachment from the filing.
  • 🔢 Get company by Ticker or Cik: You can get a company using a ticker Company("SNOW") or a 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()
  • 💰 Company Financials: You can get company financials using company.financials
  • 🔍 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
  • 👤 Insider Transactions: Search for and get insider transactions

Getting started

Install using pip

pip install edgartools

Import and start using

from edgar import *

# Tell the SEC who you are
set_identity("Michael Mccallum [email protected]")

filings = get_filings()

Concepts

How do I find a filing?

Depends on what you know

A. I know the accession number

filing = find("0001065280-23-000273")

B. I know the company ticker or cik

filings = Company("NFLX").get_filings(form="10-Q").latest(1)

C. Show me a list of filings

filings = get_filings(form="10-Q")
filing = filings[0]

What can I do with a filing

You can view it in the terminal or open it in the browser, get the filing as html, xml or text, and download attachments. You can extract data from the filing into a data object.

What can I do with a company

You can get the company's filings, facts and financials.

How to use edgartools

Task Code
Set your EDGAR identity in Linux/Mac export EDGAR_IDENTITY="First Last [email protected]"
Set your EDGAR identity in Windows set EDGAR_IDENTITY="First Last [email protected]"
Set identity in Windows Powershell $env:EDGAR_IDENTITY="First Last [email protected]"
Set identity in Python set_identity("First Last [email protected]")
Importing the library from edgar import *

Working with filings

Task 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 filigs for a range of years filings = get_filings(year=range(2010, 2020)
Get filings for a specific form filings = get_filings(form="10-K")
Get filings for a list of forms filings = get_filings(form=["10-K", "10-Q"])
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 the filings filings.sample(20)
Filter filings on a date filings = filings.filter(date="2020-01-01")
Filter filings between dates filings.filter(date="2020-01-01:2020-03-01")
Filter filings before a date filings.filter(date=":2020-03-01")
Filter filings after a date filings.filter(date="2020-03-01:")
Get filings as a pandas dataframe filings.to_pandas()

Working with a filing

Task 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 the filing homepage in the browser filing.homepage.open()
View the filing in the terminal filing.view()
Get the html of the filing document filing.html()
Get the XBRL of the filing document filing.xbrl()
Get the filing document as markdown filing.markdown()
Get the full submission text of a filing filing.text()
Get and parse the data object of a filing filing.obj()
Get the filing attachments filing.attachments
Get a single attachment attachment = filing.attachments[0]
Open an attachment in the browser attachment.open()
Download an attachment content = attachment.download()

Working with a company

Task 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 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.balance_sheet
Get the company's cash flow statement company.financials.cash_flow_statement

Installation

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.

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

export EDGAR_IDENTITY="Michael Mccallum [email protected]"

Setting EDGAR_IDENTITY in Windows Powershell

 $Env:EDGAR_IDENTITY="Michael Mccallum [email protected]"

Alternatively, you can call set_identity which does the same thing.

from edgar import set_identity
set_identity("Michael Mccallum [email protected]")

For more detail see https://www.sec.gov/os/accessing-edgar-data

Usage

Importing edgar

from edgar import *

Getting filings

# Get filings for the current year and quarter
filings = get_filings() 

# Get filings for 2022
filings = get_filings(2022)                 # OR filings = get_filings(year=2022)

# Get filings for 2022 quarter 4
filings = get_filings(2022, 4)              # OR filings = get_filings(year=2022, quarter=4)

# Get filings for 2020, 2021 and 2022
filings = get_filings([2020, 2021, 2022])   # OR filings = get_filings(year=range(2020, 2023))

# Get filings for 2020 quarters 1 and 2
filings = get_filings(2020, quarter=[1,2])

Get filings

Filtering filings

# Filter for form D
filings.filter(form="D")

# Filter for form 10-K and 10-Q 
filings.filter(form=["10-K", "10-Q"])

# When you filter by form e.g. "D" it includes amendments e.g. "D\A". You can omit amendments
filings.filter(form="D", amendments=False)

# Filter by filing_date. date and filing_date mean the same thing
# Get all filings on 2023-02-23
filings.filter(date="2023-02-23")                      
# OR
filings.filter(filing_date="2023-02-23")

# Filter to get all filings between 2023-01-23 and 2023-02-23     
filings.filter(date="2023-01-23:2023-02-23")

# Filter to get all filings since 2023-01-23   
filings.filter(date="2023-01-23")

# Filter to get all filings before 2023-02-23     
filings.filter(date=":2023-02-23")

Combining getting and filtering

get_filings(2022, form="D")

Convert the filings to a pandas dataframe

The filings data is stored in the Filings class as a pyarrow.Table. You can get the data as a pandas dataframe using to_pandas

df = filings.to_pandas()

Navigating filings

The Filings object allows you to navigate through filings using filings.next() and filings.prev(). This shows you pages of the data - the page size is about 50.

# To see the next page of data
filings.next()

# To see the previous page
filings.prev()

# To see the current page
filings.current()

Get next filings

Getting the latest filings

You can get the latest n filings by filing_date from a filings using filings.latest().

If you provide the parameter n it will return the latest n filings.

filing = filings.latest(n=5)
filing

Latest filings

If you omit this parameter, or set n=1 it will return a single `Filings object.

filing = filings.latest()
filing

Latest filing

Filtering filings

You can filter the filings object using te filter() function. This allows you to filter by filing date, or by form.

Filtering filings by date

To filter by filing date specify the filing date in YYYY-MM-DD format e.g. 2022-01-24 (Note the parameters date and filing_date are equivalent aliases for each other)

filings.filter(date="2021-01-24") # or filings.filter(filing_date="2021-01-24")

You can specify a filing date range using the colon

filings.filter(date="2021-01-12:2021-02-28") 

To filter by dates before a specified date use `:YYYY-MM-DD'

filings.filter(date=":2021-02-28") 

To filter by dates after a specified date use `YYYY-MM-DD:'

filings.filter(date="2021-02-28:") 

Filtering filings by form

You can filter filings by form using the form parameter.

filings.filter(form="10-K") 

To filter by form e.g. 10-K and include form amendments use amendments = True.

filings.filter(form="10-K", amendments=True) 

Filter with amendments

Working with a single filing

You can get a single filing from the filings using the bracket operator [], specifying the index of the filing. The index is the value displayed in the leftmost position in the filings table. For example, to get the 10-Q for Costco in the table above use filings[3]

filing = filings[3]

Costco 10Q filing

View the filing homepage

You can view the filing homepage in the terminal using filing.homepage

This gives you access to the FilingHomepage class that you can use to list all the documents and datafiles on the filing.

filing.homepage

Filing homepage

Open a filing

You can open the filing in your browser using filing.open(). This will work on environments with access to the browser, will probably not work on a remote server.

filing.open()

Open the Filing Homepage

You can open the filing homepage in the browser using filing.homepage.open().

filing.homepage.open()

View the filing as Markdown

You can view the filing's HTML content as markdown in the console using view(). It works for all filing types but can be a little slow for filings with large HTML files

filing.view()

Get the filing's html

You can get the html content of the filing using.html()

filing.html()

Get the filing's html as Markdown

You can get the html content as markdown using.markdown()

filing.markdown()

Viewing and downloading attachments

Every filing has a list of attachments. You can view the attachments using filing.attachments

# View the attachments
filing.attachments

Filing attachments

You can access each attachment using the bracket operator [] and the index of the attachment.

# Get the first attachment
attachment = filing.attachments[0]

Filing attachments

You can download the attachment using attachment.download(). This will download the attachment to string or bytes in memory.

Automatic parsing of filing data

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
And other filing with XBRL FilingXbrl

For example, to get the data object for a 13F-HR filing you can do the following:

filings = get_filings(form="13F-HR")
filing = filings[0]
thirteenf = filing.obj()

Filing attachments

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 a FilingXbrl instance, which wraps the data, and provides convenient ways of working with the xbrl data.

filing_xbrl = filing.xbrl()

Filing homapage

With the Company API you can find a company by ticker or CIK, and get the company's filings, facts and financials.

Company("AAPL")
        .get_filings(form="10-Q")
        .latest(1)
        .obj()

expe

See Using the Company API

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; 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 license.

Contact

LinkedIn

Supporters

Stargazers repo roster for @dgunning/edgartools Forkers repo roster for @dgunning/edgartools

Subscribe to Polar

2 3 Subscribe on Polar 4

About

Python library for working with SEC Edgar

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%