sec-edgar-api is a lightweight, unofficial Python API wrapper for the SEC EDGAR REST API.
- Full support for all SEC EDGAR REST API endpoints
- Automatic pagination handling for filing submissions data
- Automatic rate-limiting to 10 requests per second to conform with SEC fair access rules
- Full support for PEP 484-style type hints and the mypy type checker
- Support for Python 3.6+
Install and update this package using pip:
$ pip install -U sec-edgar-api>>> 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 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.
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.
For full documentation, please visit sec-edgar-api.readthedocs.io.