Unofficial SEC EDGAR API wrapper for Python
Project description
sec-edgar-api
sec-edgar-api is a lightweight, unofficial Python API wrapper for the SEC EDGAR REST API.
Features
- 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+
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sec_edgar_api-1.1.0.tar.gz
.
File metadata
- Download URL: sec_edgar_api-1.1.0.tar.gz
- Upload date:
- Size: 17.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: python-requests/2.31.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
edee783aa6c29e4499f04c059a9e71c9aa7af4274750a9609ba12103f82c49ab
|
|
MD5 |
e3290f6621e370acc3a3e0e75925659a
|
|
BLAKE2b-256 |
16e4e7215d9bb1f3153da6911d3578b514bd48c667f94716a5b0553823df82e9
|
File details
Details for the file sec_edgar_api-1.1.0-py3-none-any.whl
.
File metadata
- Download URL: sec_edgar_api-1.1.0-py3-none-any.whl
- Upload date:
- Size: 9.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: python-requests/2.31.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
1a07499b5235d42ce5cd347e1974ece9b21a497a6ae8397a9f1a9ae6540c9b48
|
|
MD5 |
36f95323fe776959570bbc8b9e1d2cc2
|
|
BLAKE2b-256 |
89a9bddcf0978ee82e3ef8de24c1db299c465c503bfa877efbae6afa8ddba1fc
|