edgartools 1.12.2

One of the nicest looking EDGAR libraries out there

Table of Contents

1. About The Project
   • Demo
   • Features
2. Installation
3. Usage
   • Set your Edgar user identity
   • Getting Filings
   • Using the Company API
4. Contributing
5. License
6. Contact

About the project

edgartools is one of the nicest looking EDGAR libraries out there. You can query, filter and select any filing since 1994 and view the filing's html, text, xml or structured data.

Demo

Get the latest 10 form D filings and view the first in the browser

from edgar import *

# Get form D filings for the last quarter of 2022 
filings = get_filings(2022, 4, form="D")

# Get the latest 10 filings from the list 
latest_10_filings = filings.latest(10)

# Of the 10 latest filings open the 1st in the browser
latest_10_filings[0].open()

Features

Start with filings, filter down to a filing

• View filings since 1994 to today
• Filter filings by form e.g. 10K, filing date etc.
• Page through filings using next() and prev()
• Select and view a filing in the terminal, or open in the browser
• Download any file from any filing
• Parse XML for Offering, Ownership and other filing types
• Automatically parse a filing's XBRL into a pandas dataframe

Start with a Company, get their filings and Facts

• Search for company by ticker or CIK
• View a company's filings
• Page through filings using next() and prev()
• Get a company facts e.g. CommonSharesOutstanding as a dataframe

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 [e-mail]"

Setting EDGAR_IDENTITY in Windows Powershell

 $Env:EDGAR_IDENTITY="Michael Mccallum [e-mail]"

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

from edgar import set_identity
set_identity("Michael Mccallum [e-mail]")

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

Getting filings

To get started import from edgar and use the get_filings function.

from edgar import *

filings = get_filings()

This gets the list of filings for the current year and quarter into a Filings object.

If you need a different date range you can specify a year or years and a quarter or quarters. These are valid ways to specify the date range or filter by form or by filing date.

    >>> filings = get_filings(2021) # Get filings for 2021

    >>> filings = get_filings(2021, 4) # Get filings for 2021 Q4

    >>> filings = get_filings(2021, [3,4]) # Get filings for 2021 Q3 and Q4

    >>> filings = get_filings([2020, 2021]) # Get filings for 2020 and 2021

    >>> filings = get_filings([2020, 2021], 4) # Get filings for Q4 of 2020 and 2021

    >>> filings = get_filings(range(2010, 2021)) # Get filings between 2010 and 2021 - does not include 2021

    >>> filings = get_filings(2021, 4, form="D") # Get filings for 2021 Q4 for form D

    >>> filings = get_filings(2021, 4, filing_date="2021-10-01") # Get filings for 2021 Q4 on "2021-10-01"

    >>> filings = get_filings(2021, 4, filing_date="2021-10-01:2021-10-10") # Get filings for 2021 Q4 between
                                                                            # "2021-10-01" and "2021-10-10"

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()

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

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

filing = filings.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) 

Getting 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]

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

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()

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()

Using the Company API

With the company API you find a company using the cik or ticker. From the company you can access all their historical filings, and a dataset of the company facts. The SEC's company API also supplies a lot more details about a company including industry, the SEC filer type, the mailing and business address and much more.

Find a company using the cik

The cik is the id that uniquely identifies a company at the SEC. It is a number, but is sometimes shown in SEC Edgar resources as a string padded with leading zero's. For the edgar client API, just use the numbers and omit the leading zeroes.

company = Company(1324424)

Find a company using ticker

You can get a company using a ticker e.g. SNOW. This will do a lookup for the company cik using the ticker, then load the company using the cik. This makes it two calls versus one for the cik company lookup, but is sometimes more convenient since tickers are easier to remember that ciks.

Note that some companies have multiple tickers, so you technically cannot get SEC filings for a ticker. You instead get the SEC filings for the company to which the ticker belongs.

The ticker is case-insensitive so you can use Company("snow") or Company("SNOW")

snow = Company("snow")

Company(1832950)

Get filings for a company

To get the company's filings use get_filings(). This gets all the company's filings that are available from the Edgar submissions endpoint.

company.get_filings()

Filtering filings

You can filter the company filings using a number of different parameters.

class CompanyFilings:
    
    ...
    
    def get_filings(self,
                    *,
                    form: str | List = None,
                    accession_number: str | List = None,
                    file_number: str | List = None,
                    is_xbrl: bool = None,
                    is_inline_xbrl: bool = None
                    ):
        """
        Get the company's filings and optionally filter by multiple criteria
        :param form: The form as a string e.g. '10-K' or List of strings ['10-Q', '10-K']
        :param accession_number: The accession number that uniquely identifies an SEC filing e.g. 0001640147-22-000100
        :param file_number: The file number e.g. 001-39504
        :param is_xbrl: Whether the filing is xbrl
        :param is_inline_xbrl: Whether the filing is inline_xbrl
        :return: The CompanyFiling instance with the filings that match the filters
        """

The CompanyFilings class

The result of get_filings() is a CompanyFilings class. This class contains a pyarrow table with the filings and provides convenient functions for working with filings. You can access the underlying pyarrow Table using the .data property

filings = company.get_filings()

# Get the underlying Table
data: pa.Table = filings.data

Get a filing by index

To access a filing in the CompanyFilings use the bracket [] notation e.g. filings[2]

filings[2]

Get the latest filing

The CompanyFilings class has a latest function that will return the latest Filing. So, to get the latest 10-Q filing, you do the following

# Latest filing makes sense if you filter by form  type e.g. 10-Q
snow_10Qs = snow.get_filings(form='10-Q')
latest_10Q = snow_10Qs.latest()

# Or chain the function calls
snow.get_filings(form='10-Q').latest()

Get company facts

Facts are an interesting and important dataset about a company accumlated from data the company provides to the SEC. Company facts are available for a company on the Company Factsf"https://data.sec.gov/api/xbrl/companyfacts/CIK{cik:010}.json" It is a JSON endpoint and edgartools parses the JSON into a structured dataset - a pyarrow.Table.

Getting facts for a company

To get company facts, first get the company, then call company.get_facts()

company = Company("SNOW")
company_facts = company.get_facts()

The result is a CompanyFacts object which wraps the underlying facts and provides convenient ways of working with the facts data. To get access to the underyling data use the facts property.

You can get the facts as a pandas dataframe by calling to_pandas

df = company_facts.to_pandas()

Facts differ among companies. To see what facts are available you can use the facts_meta property.

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