sec-edgar-api

Tests Documentation Status codecov PyPI Version Supported Python Versions License Code Style: Black

sec-edgar-api is a lightweight, unofficial Python API wrapper for the SEC EDGAR REST API.

Features

Quick Start

Installation

Install and update this package using pip:

$ pip install -U sec-edgar-api

Usage

>>> from sec_edgar_api import EdgarClient

# Specify user-agent string to pass to SEC to identify
# requests for rate-limiting purposes
>>> edgar = EdgarClient(user_agent="<Sample Company Name> <Admin Contact>@<Sample Company Domain>")

# Get submissions for Apple with the additional paginated files
# appended to the recent filings to prevent the need for extra
# manual pagination handling
>>> edgar.get_submissions(cik="320193")
{
    "cik": "320193",
    "entityType": "operating",
    "sic": "3571",
    "sicDescription": "Electronic Computers",
    "insiderTransactionForOwnerExists": 0,
    "insiderTransactionForIssuerExists": 1,
    "name": "Apple Inc.",
    "tickers": [
        "AAPL"
    ],
    "exchanges": [
        "Nasdaq"
    ],
    ...
    "filings": {
        "recent": {
            "accessionNumber": [...],
            "filingDate": [...],
            "reportDate": [...],
            "acceptanceDateTime": [...],
            "act": [...],
            "form": [...],
            "fileNumber": [...],
            "filmNumber": [...],
            "items": [...],
            "size": [...],
            "isXBRL": [...],
            "isInlineXBRL": [...],
            "primaryDocument": [...],
            "primaryDocDescription": [...]
        },
        # The extra paginated submission data has already been
        # appended to the lists in the above "recent" key entries
        "files": []
    }
}

# Get submissions for Apple without automatic pagination handling,
# which requires manual handling of the paginated files (not recommended)
>>> edgar.get_submissions(cik="320193", handle_pagination=False)
{
    "cik": "320193",
    "entityType": "operating",
    "sic": "3571",
    "sicDescription": "Electronic Computers",
    "insiderTransactionForOwnerExists": 0,
    "insiderTransactionForIssuerExists": 1,
    "name": "Apple Inc.",
    "tickers": [
        "AAPL"
    ],
    "exchanges": [
        "Nasdaq"
    ],
    ...
    "filings": {
        "recent": {
            "accessionNumber": [...],
            "filingDate": [...],
            "reportDate": [...],
            "acceptanceDateTime": [...],
            "act": [...],
            "form": [...],
            "fileNumber": [...],
            "filmNumber": [...],
            "items": [...],
            "size": [...],
            "isXBRL": [...],
            "isInlineXBRL": [...],
            "primaryDocument": [...],
            "primaryDocDescription": [...]
        },
        # Requires manual pagination handling
        "files": [
            {
                "name": "CIK0000320193-submissions-001.json",
                "filingCount": ...,
                "filingFrom": ...,
                "filingTo": ...
            }
        ]
    }
}

# Get company concept for Apple
>>> edgar.get_company_concept(cik="320193", taxonomy="us-gaap", tag="AccountsPayableCurrent")
{
    "cik": 320193,
    "taxonomy": "us-gaap",
    "tag": "AccountsPayableCurrent",
    "label": "Accounts Payable, Current",
    "description": ...,
    "entityName": "Apple Inc.",
    "units": {
        "USD": [...]
    }
}

# Get company facts for Apple
>>> edgar.get_company_facts(cik="320193")
{
    "cik": 320193,
    "entityName": "Apple Inc.",
    "facts": {
        "dei": {
            "EntityCommonStockSharesOutstanding": {
                "label": "Entity Common Stock, Shares Outstanding",
                "description": ...,
                "units": {
                    "shares": [...]
                }
            },
            "EntityPublicFloat": {
                "label": "Entity Public Float",
                "description": ...,
                "units": {
                    "USD": [...]
                }
            }
        },
        "us-gaap": {
            "AccountsPayable": {
                "label": "Accounts Payable (Deprecated 2009-01-31)",
                "description": ...,
                "units": {
                    "USD": [...]
                }
            },
            "AccountsPayableCurrent": {
                "label": "Accounts Payable, Current",
                "description": ...,
                "units": {
                    "USD": [...]
                }
            },
            ...
        }
    }
}

# Get one fact for each reporting entity in specified
# calendar period (Q1 2019)
>>> edgar.get_frames(taxonomy="us-gaap", tag="AccountsPayableCurrent", unit="USD", year="2019", quarter=1)
{
    "taxonomy": "us-gaap",
    "tag": "AccountsPayableCurrent",
    "ccp": "CY2019Q1I",
    "uom": "USD",
    "label": "Accounts Payable, Current",
    "description": ...,
    "pts": 3388,
    "data": [
        {
            "accn": "0001555538-19-000006",
            "cik": 1555538,
            "entityName": "SUNCOKE ENERGY PARTNERS, L.P.",
            "loc": "US-IL",
            "end": "2019-03-31",
            "val": 78300000
        },
        {
            "accn": "0000011199-19-000012",
            "cik": 11199,
            "entityName": "BEMIS CO INC",
            "loc": "US-WI",
            "end": "2019-03-31",
            "val": 465700000
        },
        ...
    ]
}

Wrapper Functions and Corresponding API Endpoints

Wrapper Function

API Route

Full API URI

get_submissions(cik)

/submissions/

data.sec.gov/submissions/CIK{cik}.json

get_company_concept(cik, taxonomy, tag)

/api/xbrl/companyconcept/

data.sec.gov/api/xbrl/companyconcept/CIK{cik}/{taxonomy}/{tag}.json

get_company_facts(cik)

/api/xbrl/companyfacts/

data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json

get_frames(taxonomy, tag, unit, year, quarter, instantaneous)

/api/xbrl/frames/

data.sec.gov/api/xbrl/frames/{taxonomy}/{tag}/{unit}/CY{year}{quarter}{instantaneous}.json

More details on each endpoint can be found on the official SEC API documentation: sec.gov/edgar/sec-api-documentation.

Contributing

If you encounter a bug or would like to see a new company filing or feature added to sec-edgar-api, please file an issue or submit a pull request.

Documentation

For full documentation, please visit sec-edgar-api.readthedocs.io.

API Guide

EdgarClient

Unofficial SEC EDGAR API wrapper.

class sec_edgar_api.EdgarClient.EdgarClient(user_agent)

An EdgarClient object.

get_company_concept(cik, taxonomy, tag)

Get company concepts for a specified CIK. Requests data from the data.sec.gov/api/xbrl/companyconcept/ API endpoint. Returns all the XBRL disclosures for a single company (CIK) and concept (taxonomy and tag), with a separate array of facts for each unit of measure that the company has chosen to disclose (e.g. net profits reported in U.S. dollars and in Canadian dollars). Full API documentation: https://www.sec.gov/edgar/sec-api-documentation.

Parameters
Return type

Dict[str, Any]

Returns

JSON response from the data.sec.gov/api/xbrl/companyconcept/ API endpoint for the specified CIK.

get_company_facts(cik)

Get all company concepts for a specified CIK. Requests data from the data.sec.gov/api/xbrl/companyfacts/ API endpoint. Full API documentation: https://www.sec.gov/edgar/sec-api-documentation.

Parameters

cik (str) – CIK to obtain company concepts for.

Return type

Dict[str, Any]

Returns

JSON response from the data.sec.gov/api/xbrl/companyfacts/ API endpoint for the specified CIK.

get_frames(taxonomy, tag, unit, year, quarter=None, instantaneous=True)

Get all aggregated company facts for a specified taxonomy and tag in the specified calendar period. Requests data from the data.sec.gov/api/xbrl/frames/ API endpoint. Supports for annual, quarterly and instantaneous data. Example: us-gaap / AccountsPayableCurrent / USD / CY2019Q1I. Full API documentation: https://www.sec.gov/edgar/sec-api-documentation.

Parameters
  • taxonomy (str) – reporting taxonomy (e.g. us-gaap, ifrs-full, dei, srt). More info: https://www.sec.gov/info/edgar/edgartaxonomies.shtml.

  • tag (str) – reporting tag (e.g. AccountsPayableCurrent).

  • unit (str) – unit of measure specified in the XBRL (e.g. USD).

  • year (str) – calendar period year.

  • quarter (Union[int, str, None]) – calendar period quarter, optional. Defaults to whole year.

  • instantaneous (bool) – whether to request instantaneous data, defaults to True.

Return type

Dict[str, Any]

Returns

JSON response from the data.sec.gov/api/xbrl/frames/ API endpoint.

get_submissions(cik, *, handle_pagination=True)

Get submissions for a specified CIK. Requests data from the data.sec.gov/submissions API endpoint. Full API documentation: https://www.sec.gov/edgar/sec-api-documentation.

Parameters
  • cik (str) – CIK to obtain submissions for.

  • handle_pagination (bool) – whether to automatically handle API pagination, defaults to True. By default, 1000 submissions are included and the response specified the next set of filenames to request to get the next batch of submissions (each page contains 1000 submissions). If this is set to True, requests to the paginated resources will be completed automatically and the results will be concatenated to the recent filings key. If a raw response is preferred for manual pagination handling, set this value to false.

Return type

Dict[str, Any]

Returns

JSON response from the data.sec.gov/submissions/ API endpoint for the specified CIK.