Skip to content

Commit 6102a8a

Browse files
janlukasschroederjanlukasschroeder
committed
added get_filings
1 parent 9929a6b commit 6102a8a

2 files changed

Lines changed: 133 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 121 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,108 @@
1-
# sec.gov EDGAR filings real-time API
2-
3-
- Covers SEC Edgar filings for **over 8000** publicly listed companies, ETFs, hedge funds, mutual funds, and investors.
4-
- Every filing is **mapped to a CIK and ticker**.
5-
- **Over 150 form types** are supported, eg 10-Q, 10-K, 4, 8-K, 13-F and many more.
6-
[See the list of supported form types here.](https://sec-api.io/#list-of-sec-form-types)
7-
- The API returns a new filing as soon as it is published on SEC EDGAR.
8-
- **No XBRL/XML** needed - JSON formatted.
1+
# SEC API - A SEC.gov EDGAR Filings Query & Real-Time Stream API
2+
3+
**sec-api** is a Python package for querying the entire SEC filings corpus in real-time without the need to download filings.
4+
It includes:
5+
6+
- Query and Full-Text Search API
7+
- Real-Time Stream API
8+
- Filings Render API
9+
10+
11+
# Data Coverage
12+
13+
- All +18 million SEC EDGAR filings dating back to 1993
14+
- **All +150 filing types** are supported, eg 10-Q, 10-K, 4, 8-K, 13-F, S-1, 424B4 and many more.
15+
[See the list of supported form types here.](https://sec-api.io/list-of-sec-filing-types)
16+
- Newly published filings are accessible in real-time
917
- 13F holdings API included. Monitor all institutional ownerships in real-time.
10-
- Python, R, Java, C++, Excel scripts are supported through websockets
11-
- Client- and server-side JavaScript supported (Node.js, React, React Native, Angular, Vue, etc.)
18+
- Every filing is **mapped to a CIK and ticker**
19+
- All filings in JSON - **no XBRL/XML**
20+
21+
Data source: [sec.gov](https://www.sec.gov/edgar/searchedgar/companysearch.html)
22+
23+
# Overview
24+
25+
- The query API gives access to all over 18 million SEC Edgar filings of **over 8000**
26+
publicly listed companies, ETFs, hedge funds, mutual funds, and investors dating back to 1993.
27+
- Connect to the real-time stream API to receive new filings as soon as they are published on SEC EDGAR
28+
- The full-text search API allows you to search the full text of all filings submitted since 2001.
29+
The full text of a filing includes all data in the filing itself as well as all attachments (such as exhibits) to the filing.
1230
- Free API key available on [sec-api.io](https://sec-api.io)
1331

14-
The official documentation explains how to use the
15-
query API to filter historical filings: [sec-api.io/docs](https://sec-api.io/docs)
32+
See the official documentation for more: [sec-api.io/docs](https://sec-api.io/docs)
1633

17-
Data source: [sec.gov](https://www.sec.gov/edgar/searchedgar/companysearch.html)
34+
# Installation
35+
36+
```bash
37+
pip install sec-api
38+
```
39+
40+
Get your free API key on [sec-api.io](https://sec-api.io) and replace `YOUR_API_KEY` with it.
41+
42+
43+
# SEC EDGAR Filings Query API
44+
45+
The below example retrieves all 10-Q filings filed by TSLA in 2020.
46+
47+
```python
48+
from sec_api import QueryApi
49+
50+
queryApi = QueryApi(api_key='YOUR_API_KEY')
1851

19-
# Getting Started
52+
query = {
53+
"query": { "query_string": {
54+
"query": "ticker:TSLA AND filedAt:{2020-01-01 TO 2020-12-31} AND formType:\"10-Q\""
55+
} },
56+
"from": "0",
57+
"size": "10",
58+
"sort": [{ "filedAt": { "order": "desc" } }]
59+
}
60+
61+
filings = queryApi.get_filings(query)
2062

21-
You can use the API in your command line, or develop your own application
22-
using the API as imported package. Both options are explained below.
63+
print(filings)
64+
```
2365

66+
Fetch most recent 8-Ks with item 9.01
67+
68+
```python
69+
query = {
70+
"query": { "query_string": {
71+
"query": "formType:\"8-K\" AND description:\"9.01\""
72+
} },
73+
"from": "0",
74+
"size": "10",
75+
"sort": [{ "filedAt": { "order": "desc" } }]
76+
}
2477

25-
## Command Line
78+
filings = queryApi.get_filings(query)
79+
```
2680

27-
In your command line, type
81+
Fetch most recent 13F filings that hold Tesla
2882

29-
1. `python -m pip install sec-api` to install the package
30-
2. `sec-api YOUR_API_KEY` to connect to the stream. Replace `YOUR_API_KEY` with
31-
the API key provided on [sec-api.io](https://sec-api.io)
32-
3. Done! You will see new filings printed in your command line
33-
as soon as they are published on SEC EDGAR.
83+
```python
84+
query = {
85+
"query": { "query_string": {
86+
"query": "formType:\"13F\" AND holdings.cusip:88160R101"
87+
} },
88+
"from": "0",
89+
"size": "10",
90+
"sort": [{ "filedAt": { "order": "desc" } }]
91+
}
3492

93+
filings = queryApi.get_filings(query)
94+
```
3595

36-
## Python
3796

38-
- Install the socket.io client: `pip install "python-socketio[client]"`
39-
- Run the example script below. Get your free API key on [sec-api.io](https://sec-api.io)
97+
# SEC EDGAR Filings Real-Time Stream API
98+
99+
Install the `socketio` client:
100+
101+
```bash
102+
pip install python-engineio==3.14.2 python-socketio[client]==4.6.0`
103+
```
104+
105+
Run the example script below. Get your free API key on [sec-api.io](https://sec-api.io)
40106
and replace `YOUR_API_KEY` with it.
41107

42108
```python
@@ -58,7 +124,6 @@ sio.wait()
58124

59125

60126

61-
62127
# Response Format
63128

64129
- `accessionNo` (string) - Accession number of filing, e.g. 0000028917-20-000033
@@ -73,6 +138,8 @@ sio.wait()
73138
- `linkToHtml` (string) - Link to index page of the filing listing all exhibits and the original HTML file.
74139
- `linkToXbrl` (string, optional) - Link to XBRL version of the filing (if available).
75140
- `filedAt` (string) - The date (format: YYYY-MM-DD HH:mm:SS TZ) the filing was filed, eg 2019-12-06T14:41:26-05:00.
141+
- `periodOfReport` (string, if reported) - Period of report, e.g. 2021-06-08
142+
- `effectivenessDate` (string, if reported) - Effectiveness date, e.g. 2021-06-08
76143
- `id` (string) - Unique ID of the filing.
77144
- `entities` (array) - A list of all entities referred to in the filing. The first item in the array always represents the filing issuer. Each array element is an object with the following keys:
78145
- `companyName` (string) - Company name of the entity, e.g. DILLARD'S, INC. (Issuer)
@@ -97,6 +164,33 @@ sio.wait()
97164
- `documentUrl` (string) - URL to the file on SEC.gov
98165
- `type` (string, optional) - Type of the file, e.g. EX-101.INS, EX-101.DEF or EX-101.PRE
99166
- `size` (string, optional) - Size of the file, e.g. 6627216
167+
- `seriesAndClassesContractsInformation` (array) - List of series and classes/contracts information
168+
- `series` (string) - Series ID, e.g. S000001297
169+
- `name` (string) - Name of entity, e.g. PRUDENTIAL ANNUITIES LIFE ASSUR CORP VAR ACCT B CL 1 SUB ACCTS
170+
- `classesContracts` (array) - List of classes/contracts. Each list item has the following keys:
171+
- `classContract` (string) - Class/Contract ID, e.g. C000011787
172+
- `name` (string) - Name of class/contract entity, e.g. Class L
173+
- `ticker` (string) - Ticker class/contract entity, e.g. URTLX
174+
175+
176+
## 13F Institutional Ownerships
177+
178+
13F filings report institutional ownerships. Each 13F filing has an attribute `holdings` (array). An array item in holdings represents one holding and has the following attributes:
179+
180+
- `nameOfIssuer` (string) - Name of issuer, e.g. MICRON TECHNOLOGY INC
181+
- `titleOfClass` (string) - Title of class, e.g. COM
182+
- `cusip` (string) - CUSIP of security, e.g. 98850P109
183+
- `value` (integer) - Absolute holding value in $, e.g. 18000. Note: `value` doesn't have to be multiplied by 1000 anymore. It's done by our API automatically.
184+
- `shrsOrPrnAmt` (object)
185+
- `sshPrnamt` (integer) - Shares or PRN AMT, e.g. 345
186+
- `sshPrnamtType` (string) - Share/PRN type, e.g. "SH"
187+
- `putCall` (string, optional) - Put / Call, e.g. Put
188+
- `investmentDiscretion` (string) - Investment discretion, e.g. "SOLE"
189+
- `otherManager` (string, optional) - Other manager, e.g. 7
190+
- `votingAuthority` (object)
191+
- `Sole` (integer) - Sole, e.g. 345
192+
- `Shared` (integer) - Shared, e.g. 345
193+
- `None` (integer) - None, e.g. 345
100194

101195
## Example JSON Response
102196

‎index.py‎

Lines changed: 12 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,16 @@
1-
#!/usr/bin/python
1+
import requests
22

3-
import sys
4-
import socketio
5-
import pprint
3+
query_api_endpoint = 'https://api.sec-api.io'
64

7-
pp = pprint.PrettyPrinter(indent=4)
8-
sio = socketio.Client()
95

10-
server_url = 'https://api.sec-api.io:3334'
11-
api_key = str(sys.argv[1])
12-
connection_string = server_url + '?apiKey=' + api_key
6+
class QueryApi:
7+
"""
8+
Base class for Query API
9+
"""
10+
def __init__(self, api_key):
11+
self.api_key = api_key
12+
self.api_endpoint = query_api_endpoint + '?token=' + api_key
1313

14-
15-
@sio.on('connect', namespace='/all-filings')
16-
def on_connect():
17-
print("Connected to https://api.sec-api.io:3334")
18-
19-
20-
@sio.on('filing', namespace='/all-filings')
21-
def on_filing(filing):
22-
formatted = pp.pformat(filing)
23-
print(formatted)
24-
25-
26-
@sio.on('error', namespace='/all-filings')
27-
def on_error(error):
28-
print("Error", error)
29-
30-
31-
@sio.event
32-
def disconnect():
33-
print('Disconnected from server')
34-
35-
36-
sio.connect(connection_string, namespaces=['/all-filings'])
37-
sio.wait()
14+
def get_filings(self, query):
15+
response = requests.post(self.api_endpoint, json=query)
16+
return response.json()

0 commit comments

Comments
 (0)