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:
  • cik (str) – CIK to obtain company concepts for.

  • 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).

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.