bankregreports 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bankregreports-0.2.0/LICENSE +33 -0
- bankregreports-0.2.0/PKG-INFO +290 -0
- bankregreports-0.2.0/README.md +250 -0
- bankregreports-0.2.0/bankregreports.egg-info/PKG-INFO +290 -0
- bankregreports-0.2.0/bankregreports.egg-info/SOURCES.txt +9 -0
- bankregreports-0.2.0/bankregreports.egg-info/dependency_links.txt +1 -0
- bankregreports-0.2.0/bankregreports.egg-info/requires.txt +8 -0
- bankregreports-0.2.0/bankregreports.egg-info/top_level.txt +1 -0
- bankregreports-0.2.0/bankregreports.py +2034 -0
- bankregreports-0.2.0/pyproject.toml +91 -0
- bankregreports-0.2.0/setup.cfg +4 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
BankRegReports LLC — Proprietary License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024-2026 BankRegReports LLC. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This software (the "BankRegReports Python API Client" and all accompanying
|
|
6
|
+
source code, documentation, and files in this package) is the exclusive
|
|
7
|
+
intellectual property of BankRegReports LLC, a company organized under the laws
|
|
8
|
+
of the State of Georgia, USA.
|
|
9
|
+
|
|
10
|
+
This package is provided to authorized customers solely to access the
|
|
11
|
+
BankRegReports Data API under the terms of their API subscription agreement and
|
|
12
|
+
the BankRegReports Terms of Service (https://www.bankregreports.com/terms/).
|
|
13
|
+
|
|
14
|
+
Restrictions
|
|
15
|
+
------------
|
|
16
|
+
Unless prior written consent has been obtained from BankRegReports LLC:
|
|
17
|
+
- The source code may not be redistributed, sublicensed, sold, or published.
|
|
18
|
+
- The software may not be reverse-engineered to reconstruct or reproduce the
|
|
19
|
+
BankRegReports Data API or its underlying datasets.
|
|
20
|
+
- The software may not be used to circumvent API authentication, rate limits,
|
|
21
|
+
quotas, or subscription tiers.
|
|
22
|
+
|
|
23
|
+
Use of the BankRegReports Data API is additionally governed by the API Terms of
|
|
24
|
+
Service. Data returned by the API is licensed, not sold, and remains subject to
|
|
25
|
+
those terms.
|
|
26
|
+
|
|
27
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
28
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
29
|
+
FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL BANKREGREPORTS
|
|
30
|
+
LLC BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF,
|
|
31
|
+
OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
|
|
32
|
+
|
|
33
|
+
Contact: admin@bankregreports.com
|
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bankregreports
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Python client for the BankRegReports Data API — regulatory data on every US bank, credit union, and holding company.
|
|
5
|
+
Author-email: BankRegReports LLC <admin@bankregreports.com>
|
|
6
|
+
License: Proprietary
|
|
7
|
+
Project-URL: Homepage, https://www.bankregreports.com
|
|
8
|
+
Project-URL: Documentation, https://www.bankregreports.com/api/
|
|
9
|
+
Project-URL: API Docs, https://api.bankregreports.com/api/v1/docs/
|
|
10
|
+
Project-URL: API Sign-up, https://www.bankregreports.com/api/
|
|
11
|
+
Project-URL: Source, https://github.com/BankRegReports-LLC/python-api
|
|
12
|
+
Project-URL: Changelog, https://github.com/BankRegReports-LLC/python-api/blob/main/CHANGELOG.md
|
|
13
|
+
Keywords: banking,bank-regulatory-data,fdic,ffiec,call-report,ubpr,ncua,regulatory-data,financial-data,bank-data,fintech,pandas,api-client,us-banks,holding-company,credit-union,risk,sec-edgar,community-banking,bank-failure-prediction,cecl,alco
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial :: Investment
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
27
|
+
Classifier: License :: Other/Proprietary License
|
|
28
|
+
Classifier: Operating System :: OS Independent
|
|
29
|
+
Classifier: Typing :: Typed
|
|
30
|
+
Requires-Python: >=3.8
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
License-File: LICENSE
|
|
33
|
+
Requires-Dist: requests>=2.25
|
|
34
|
+
Provides-Extra: pandas
|
|
35
|
+
Requires-Dist: pandas>=1.3; extra == "pandas"
|
|
36
|
+
Provides-Extra: dev
|
|
37
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
38
|
+
Requires-Dist: requests-mock>=1.11; extra == "dev"
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
# bankregreports — BankRegAPI Python SDK
|
|
42
|
+
|
|
43
|
+
[](https://pypi.org/project/bankregreports/)
|
|
44
|
+
[](https://www.python.org/downloads/)
|
|
45
|
+
[](https://peps.python.org/pep-0561/)
|
|
46
|
+
[](https://api.bankregreports.com/api/v1/docs/)
|
|
47
|
+
[](https://www.bankregreports.com/api/)
|
|
48
|
+
|
|
49
|
+
Python client for the **[BankRegReports Data API](https://www.bankregreports.com)** —
|
|
50
|
+
clean, validated, cross-source regulatory data on every US bank, credit union, and holding
|
|
51
|
+
company, sourced from FFIEC Call Reports, UBPR, FDIC, Federal Reserve, NCUA, and SEC EDGAR.
|
|
52
|
+
|
|
53
|
+
**[Full SDK docs](https://www.bankregreports.com/api/)**
|
|
54
|
+
·
|
|
55
|
+
**[Swagger / OpenAPI](https://api.bankregreports.com/api/v1/docs/)**
|
|
56
|
+
·
|
|
57
|
+
**[Get API key](https://www.bankregreports.com/api/)**
|
|
58
|
+
·
|
|
59
|
+
**[bankregreports.com](https://www.bankregreports.com)**
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Why BankRegReports
|
|
64
|
+
|
|
65
|
+
Raw US bank regulatory data is public but arrives as pipe-delimited bulk files with cryptic
|
|
66
|
+
MDRM codes, four competing unit conventions, silent schema changes between quarters, and
|
|
67
|
+
no linkage between FDIC, FFIEC, Federal Reserve, and SEC identifiers. Cleaning it to a
|
|
68
|
+
usable state takes months. Enterprise data platforms solve this — at $20K–$200K+/year with
|
|
69
|
+
multi-year contracts.
|
|
70
|
+
|
|
71
|
+
**[BankRegReports](https://www.bankregreports.com)** is the middle ground: the same
|
|
72
|
+
cleaned, validated, cross-source-linked data through a modern REST API with a Python SDK,
|
|
73
|
+
at a fraction of the cost. Built by practitioners who have been in ALCO, been through
|
|
74
|
+
regulatory exams, and needed this data to actually exist.
|
|
75
|
+
|
|
76
|
+
Read the full background: **[Why We Built BankRegReports →](https://www.bankregreports.com)**
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Installation
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
pip install bankregreports
|
|
84
|
+
# with pandas (recommended)
|
|
85
|
+
pip install "bankregreports[pandas]"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Requires:** Python 3.8+ · `requests>=2.25`
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Quick start
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
import bankregreports
|
|
96
|
+
|
|
97
|
+
# Set BANKREG_API_TOKEN env var, or pass the token directly
|
|
98
|
+
brr = bankregreports.BankReg("brr_xxx")
|
|
99
|
+
|
|
100
|
+
# Screen every US bank — returns a pandas DataFrame
|
|
101
|
+
df = brr.screener(state="GA", min_assets=500_000)
|
|
102
|
+
print(df[["legal_name", "total_assets", "cet1_ratio", "roa"]].head(10))
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Works as a context manager:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
with bankregreports.BankReg("brr_xxx") as brr:
|
|
109
|
+
df_banks = brr.screener(state="TX")
|
|
110
|
+
df_rates = brr.rates("mortgage")
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Authentication
|
|
116
|
+
|
|
117
|
+
Get a free API key at **[bankregreports.com/api](https://www.bankregreports.com/api/)**.
|
|
118
|
+
All keys begin with `brr_`.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
# Explicit token
|
|
122
|
+
brr = bankregreports.BankReg("brr_xxx")
|
|
123
|
+
|
|
124
|
+
# Environment variable (recommended)
|
|
125
|
+
# export BANKREG_API_TOKEN=brr_xxx
|
|
126
|
+
brr = bankregreports.BankReg()
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Coverage — 101 datasets across 16 domains
|
|
132
|
+
|
|
133
|
+
| Domain | What you get |
|
|
134
|
+
|---|---|
|
|
135
|
+
| Banks — snapshot & trends | Latest metrics, 20-quarter time series, full Call Report/UBPR detail |
|
|
136
|
+
| Banks — scores & peers | CAMELS-style scores, percentile ranks, peer benchmarks |
|
|
137
|
+
| Banks — sub-books | Deposits, securities (HTM/AFS/unrealized G/L), loans, HMDA |
|
|
138
|
+
| Banks — structure | Parent chain, subsidiaries, NIC events, FDIC history, FRY-15 |
|
|
139
|
+
| Branches | FDIC SoD + NIC combined, rollup stats, map-ready lat/lon |
|
|
140
|
+
| Risk & compliance | ML failure prediction + feature attribution, enforcement actions, CFPB complaints |
|
|
141
|
+
| Screeners | Full-universe filter, M&A target scoring, CRE concentration, growth |
|
|
142
|
+
| SEC / EDGAR | 10-K/10-Q/8-K, XBRL facts, insider Form-4, exec comp, 13D/G, 13F |
|
|
143
|
+
| Industry & macro | Aggregates, rate environment, credit spreads, VIX |
|
|
144
|
+
| Rates & yield curve | Mortgage, T-bill, real yield, consumer, FDIC national deposit rates |
|
|
145
|
+
| Failures & events | FDIC failure feed, M&A/charter events, enforcement feed |
|
|
146
|
+
| Credit unions (NCUA) | 5300 Call Report, trends, branches, ATMs, peer benchmarks |
|
|
147
|
+
| Holding companies | Y-9C BHC snapshot and quarterly trends |
|
|
148
|
+
| CECL & analytics | Macro-conditioned lifetime ECL, DFAST scenarios |
|
|
149
|
+
| Watchlist & alerts | Track institutions, threshold alerts on any metric |
|
|
150
|
+
| Reference & catalog | MDRM definitions, metric catalog with formulas |
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## API reference (selected methods)
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
# ── Banks ──────────────────────────────────────────────────────────────────
|
|
158
|
+
brr.bank(852218) # latest snapshot
|
|
159
|
+
brr.bank_trends(852218, quarters=12) # quarterly time series
|
|
160
|
+
brr.bank_deep_dive(852218) # full Call Report/UBPR detail (~150 fields)
|
|
161
|
+
brr.bank_profile(852218) # snapshot + scorecard + ranks + ML prediction
|
|
162
|
+
brr.bank_compare([852218, 480228, 37]) # side-by-side comparison
|
|
163
|
+
brr.screener(state="GA", min_assets=500_000) # filter the full ~4,400-bank universe
|
|
164
|
+
brr.scorecard(852218) # CAMELS-style letter grade + component scores
|
|
165
|
+
brr.peer_comparison(852218) # bank vs. peer benchmarks
|
|
166
|
+
|
|
167
|
+
# ── Sub-books ──────────────────────────────────────────────────────────────
|
|
168
|
+
brr.bank_deposits(852218, trends=True) # deposit composition trends
|
|
169
|
+
brr.bank_securities(852218) # HTM/AFS, unrealized G/L, OTTI
|
|
170
|
+
brr.loan_portfolio(852218) # CRE, C&I, consumer, ag concentrations
|
|
171
|
+
brr.bank_hmda(852218) # HMDA mortgage lending
|
|
172
|
+
|
|
173
|
+
# ── Risk & analytics ───────────────────────────────────────────────────────
|
|
174
|
+
brr.prediction(852218, detail=True) # ML failure probability + feature attribution
|
|
175
|
+
brr.ma_screener() # M&A target scoring + valuation
|
|
176
|
+
brr.enforcement_actions(852218) # FDIC/OCC/FRB/CFPB enforcement history
|
|
177
|
+
|
|
178
|
+
# ── SEC / EDGAR ────────────────────────────────────────────────────────────
|
|
179
|
+
brr.sec_filings(852218) # 10-K, 10-Q, 8-K, proxy index
|
|
180
|
+
brr.sec_insider_txns(852218) # Form-4 insider buy/sell
|
|
181
|
+
brr.sec_13f(852218) # institutional holdings
|
|
182
|
+
brr.executive_comp(852218) # NEO compensation from proxy
|
|
183
|
+
|
|
184
|
+
# ── Credit unions (NCUA) ───────────────────────────────────────────────────
|
|
185
|
+
brr.credit_union(5536, trends=True) # 5300 Call Report snapshot + trends
|
|
186
|
+
brr.cu_peer_benchmarks() # CU peer benchmarks by asset tier
|
|
187
|
+
|
|
188
|
+
# ── Rates & macro ──────────────────────────────────────────────────────────
|
|
189
|
+
brr.rates("mortgage") # Freddie Mac 30yr/15yr series
|
|
190
|
+
brr.yield_curve(latest=True) # current yield curve snapshot
|
|
191
|
+
brr.industry(trends=True, quarters=20) # 20-quarter industry aggregate trend
|
|
192
|
+
|
|
193
|
+
# ── Generic accessor ───────────────────────────────────────────────────────
|
|
194
|
+
brr.list_datasets() # all 101 datasets: name, path, tier
|
|
195
|
+
brr.dataset("screener", state="GA") # forward-compatible generic accessor
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Full reference: **[www.bankregreports.com/api/](https://www.bankregreports.com/api/)**
|
|
199
|
+
·
|
|
200
|
+
Interactive REST docs: **[api.bankregreports.com/api/v1/docs/](https://api.bankregreports.com/api/v1/docs/)**
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Pagination
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
import pandas as pd
|
|
208
|
+
|
|
209
|
+
# Iterate pages, 200 rows at a time
|
|
210
|
+
for page in brr.pages("screener", page_size=200, state="CA"):
|
|
211
|
+
process(page)
|
|
212
|
+
|
|
213
|
+
# Collect all pages into one DataFrame
|
|
214
|
+
all_banks = pd.concat(brr.pages("screener", page_size=500))
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Error handling
|
|
220
|
+
|
|
221
|
+
All errors subclass `BankRegError`. GET requests auto-retry with exponential backoff on
|
|
222
|
+
`429` and `5xx` (default 3 retries).
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
from bankregreports import (
|
|
226
|
+
BankReg, BankRegError,
|
|
227
|
+
AuthenticationError, UpgradeRequiredError, NotFoundError,
|
|
228
|
+
RateLimitError, ValidationError, ServerError,
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
try:
|
|
232
|
+
df = brr.ma_screener()
|
|
233
|
+
except UpgradeRequiredError:
|
|
234
|
+
print("Upgrade at bankregreports.com/api/")
|
|
235
|
+
except RateLimitError as e:
|
|
236
|
+
time.sleep(e.retry_after)
|
|
237
|
+
except NotFoundError:
|
|
238
|
+
print("Institution not found")
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
| Exception | HTTP | Meaning |
|
|
242
|
+
|---|---|---|
|
|
243
|
+
| `AuthenticationError` | 401 | Missing or revoked API key |
|
|
244
|
+
| `UpgradeRequiredError` | 403 | Plan doesn't cover this dataset |
|
|
245
|
+
| `NotFoundError` | 404 | Institution or resource not found |
|
|
246
|
+
| `ValidationError` | 422 | Invalid parameters |
|
|
247
|
+
| `RateLimitError` | 429 | Throttled — check `e.retry_after` |
|
|
248
|
+
| `ServerError` | 5xx | Server error (auto-retried) |
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Configuration
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
brr = bankregreports.BankReg(
|
|
256
|
+
token="brr_xxx", # or BANKREG_API_TOKEN env var
|
|
257
|
+
base_url="http://localhost:8000",
|
|
258
|
+
timeout=30,
|
|
259
|
+
max_retries=3,
|
|
260
|
+
)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## Response format
|
|
266
|
+
|
|
267
|
+
All list-returning methods return a `pandas.DataFrame` by default (requires `pandas`
|
|
268
|
+
extra). Date columns are coerced to `datetime64`. The server response envelope is
|
|
269
|
+
available on `df.attrs["meta"]`.
|
|
270
|
+
|
|
271
|
+
Pass `as_dataframe=False` to any method for raw decoded JSON with no pandas dependency.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Resources
|
|
276
|
+
|
|
277
|
+
| | |
|
|
278
|
+
|---|---|
|
|
279
|
+
| Platform | [bankregreports.com](https://www.bankregreports.com) |
|
|
280
|
+
| API sign-up | [bankregreports.com/api](https://www.bankregreports.com/api/) |
|
|
281
|
+
| Swagger / REST docs | [api.bankregreports.com/api/v1/docs/](https://api.bankregreports.com/api/v1/docs/) |
|
|
282
|
+
| SDK docs | [www.bankregreports.com/api/](https://www.bankregreports.com/api/) |
|
|
283
|
+
| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
|
|
284
|
+
| Support | [admin@bankregreports.com](mailto:admin@bankregreports.com) |
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## License
|
|
289
|
+
|
|
290
|
+
Copyright © 2024–2026 BankRegReports LLC. Proprietary — see [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# bankregreports — BankRegAPI Python SDK
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/bankregreports/)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://peps.python.org/pep-0561/)
|
|
6
|
+
[](https://api.bankregreports.com/api/v1/docs/)
|
|
7
|
+
[](https://www.bankregreports.com/api/)
|
|
8
|
+
|
|
9
|
+
Python client for the **[BankRegReports Data API](https://www.bankregreports.com)** —
|
|
10
|
+
clean, validated, cross-source regulatory data on every US bank, credit union, and holding
|
|
11
|
+
company, sourced from FFIEC Call Reports, UBPR, FDIC, Federal Reserve, NCUA, and SEC EDGAR.
|
|
12
|
+
|
|
13
|
+
**[Full SDK docs](https://www.bankregreports.com/api/)**
|
|
14
|
+
·
|
|
15
|
+
**[Swagger / OpenAPI](https://api.bankregreports.com/api/v1/docs/)**
|
|
16
|
+
·
|
|
17
|
+
**[Get API key](https://www.bankregreports.com/api/)**
|
|
18
|
+
·
|
|
19
|
+
**[bankregreports.com](https://www.bankregreports.com)**
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Why BankRegReports
|
|
24
|
+
|
|
25
|
+
Raw US bank regulatory data is public but arrives as pipe-delimited bulk files with cryptic
|
|
26
|
+
MDRM codes, four competing unit conventions, silent schema changes between quarters, and
|
|
27
|
+
no linkage between FDIC, FFIEC, Federal Reserve, and SEC identifiers. Cleaning it to a
|
|
28
|
+
usable state takes months. Enterprise data platforms solve this — at $20K–$200K+/year with
|
|
29
|
+
multi-year contracts.
|
|
30
|
+
|
|
31
|
+
**[BankRegReports](https://www.bankregreports.com)** is the middle ground: the same
|
|
32
|
+
cleaned, validated, cross-source-linked data through a modern REST API with a Python SDK,
|
|
33
|
+
at a fraction of the cost. Built by practitioners who have been in ALCO, been through
|
|
34
|
+
regulatory exams, and needed this data to actually exist.
|
|
35
|
+
|
|
36
|
+
Read the full background: **[Why We Built BankRegReports →](https://www.bankregreports.com)**
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install bankregreports
|
|
44
|
+
# with pandas (recommended)
|
|
45
|
+
pip install "bankregreports[pandas]"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Requires:** Python 3.8+ · `requests>=2.25`
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Quick start
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import bankregreports
|
|
56
|
+
|
|
57
|
+
# Set BANKREG_API_TOKEN env var, or pass the token directly
|
|
58
|
+
brr = bankregreports.BankReg("brr_xxx")
|
|
59
|
+
|
|
60
|
+
# Screen every US bank — returns a pandas DataFrame
|
|
61
|
+
df = brr.screener(state="GA", min_assets=500_000)
|
|
62
|
+
print(df[["legal_name", "total_assets", "cet1_ratio", "roa"]].head(10))
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Works as a context manager:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
with bankregreports.BankReg("brr_xxx") as brr:
|
|
69
|
+
df_banks = brr.screener(state="TX")
|
|
70
|
+
df_rates = brr.rates("mortgage")
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Authentication
|
|
76
|
+
|
|
77
|
+
Get a free API key at **[bankregreports.com/api](https://www.bankregreports.com/api/)**.
|
|
78
|
+
All keys begin with `brr_`.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
# Explicit token
|
|
82
|
+
brr = bankregreports.BankReg("brr_xxx")
|
|
83
|
+
|
|
84
|
+
# Environment variable (recommended)
|
|
85
|
+
# export BANKREG_API_TOKEN=brr_xxx
|
|
86
|
+
brr = bankregreports.BankReg()
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Coverage — 101 datasets across 16 domains
|
|
92
|
+
|
|
93
|
+
| Domain | What you get |
|
|
94
|
+
|---|---|
|
|
95
|
+
| Banks — snapshot & trends | Latest metrics, 20-quarter time series, full Call Report/UBPR detail |
|
|
96
|
+
| Banks — scores & peers | CAMELS-style scores, percentile ranks, peer benchmarks |
|
|
97
|
+
| Banks — sub-books | Deposits, securities (HTM/AFS/unrealized G/L), loans, HMDA |
|
|
98
|
+
| Banks — structure | Parent chain, subsidiaries, NIC events, FDIC history, FRY-15 |
|
|
99
|
+
| Branches | FDIC SoD + NIC combined, rollup stats, map-ready lat/lon |
|
|
100
|
+
| Risk & compliance | ML failure prediction + feature attribution, enforcement actions, CFPB complaints |
|
|
101
|
+
| Screeners | Full-universe filter, M&A target scoring, CRE concentration, growth |
|
|
102
|
+
| SEC / EDGAR | 10-K/10-Q/8-K, XBRL facts, insider Form-4, exec comp, 13D/G, 13F |
|
|
103
|
+
| Industry & macro | Aggregates, rate environment, credit spreads, VIX |
|
|
104
|
+
| Rates & yield curve | Mortgage, T-bill, real yield, consumer, FDIC national deposit rates |
|
|
105
|
+
| Failures & events | FDIC failure feed, M&A/charter events, enforcement feed |
|
|
106
|
+
| Credit unions (NCUA) | 5300 Call Report, trends, branches, ATMs, peer benchmarks |
|
|
107
|
+
| Holding companies | Y-9C BHC snapshot and quarterly trends |
|
|
108
|
+
| CECL & analytics | Macro-conditioned lifetime ECL, DFAST scenarios |
|
|
109
|
+
| Watchlist & alerts | Track institutions, threshold alerts on any metric |
|
|
110
|
+
| Reference & catalog | MDRM definitions, metric catalog with formulas |
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## API reference (selected methods)
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
# ── Banks ──────────────────────────────────────────────────────────────────
|
|
118
|
+
brr.bank(852218) # latest snapshot
|
|
119
|
+
brr.bank_trends(852218, quarters=12) # quarterly time series
|
|
120
|
+
brr.bank_deep_dive(852218) # full Call Report/UBPR detail (~150 fields)
|
|
121
|
+
brr.bank_profile(852218) # snapshot + scorecard + ranks + ML prediction
|
|
122
|
+
brr.bank_compare([852218, 480228, 37]) # side-by-side comparison
|
|
123
|
+
brr.screener(state="GA", min_assets=500_000) # filter the full ~4,400-bank universe
|
|
124
|
+
brr.scorecard(852218) # CAMELS-style letter grade + component scores
|
|
125
|
+
brr.peer_comparison(852218) # bank vs. peer benchmarks
|
|
126
|
+
|
|
127
|
+
# ── Sub-books ──────────────────────────────────────────────────────────────
|
|
128
|
+
brr.bank_deposits(852218, trends=True) # deposit composition trends
|
|
129
|
+
brr.bank_securities(852218) # HTM/AFS, unrealized G/L, OTTI
|
|
130
|
+
brr.loan_portfolio(852218) # CRE, C&I, consumer, ag concentrations
|
|
131
|
+
brr.bank_hmda(852218) # HMDA mortgage lending
|
|
132
|
+
|
|
133
|
+
# ── Risk & analytics ───────────────────────────────────────────────────────
|
|
134
|
+
brr.prediction(852218, detail=True) # ML failure probability + feature attribution
|
|
135
|
+
brr.ma_screener() # M&A target scoring + valuation
|
|
136
|
+
brr.enforcement_actions(852218) # FDIC/OCC/FRB/CFPB enforcement history
|
|
137
|
+
|
|
138
|
+
# ── SEC / EDGAR ────────────────────────────────────────────────────────────
|
|
139
|
+
brr.sec_filings(852218) # 10-K, 10-Q, 8-K, proxy index
|
|
140
|
+
brr.sec_insider_txns(852218) # Form-4 insider buy/sell
|
|
141
|
+
brr.sec_13f(852218) # institutional holdings
|
|
142
|
+
brr.executive_comp(852218) # NEO compensation from proxy
|
|
143
|
+
|
|
144
|
+
# ── Credit unions (NCUA) ───────────────────────────────────────────────────
|
|
145
|
+
brr.credit_union(5536, trends=True) # 5300 Call Report snapshot + trends
|
|
146
|
+
brr.cu_peer_benchmarks() # CU peer benchmarks by asset tier
|
|
147
|
+
|
|
148
|
+
# ── Rates & macro ──────────────────────────────────────────────────────────
|
|
149
|
+
brr.rates("mortgage") # Freddie Mac 30yr/15yr series
|
|
150
|
+
brr.yield_curve(latest=True) # current yield curve snapshot
|
|
151
|
+
brr.industry(trends=True, quarters=20) # 20-quarter industry aggregate trend
|
|
152
|
+
|
|
153
|
+
# ── Generic accessor ───────────────────────────────────────────────────────
|
|
154
|
+
brr.list_datasets() # all 101 datasets: name, path, tier
|
|
155
|
+
brr.dataset("screener", state="GA") # forward-compatible generic accessor
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Full reference: **[www.bankregreports.com/api/](https://www.bankregreports.com/api/)**
|
|
159
|
+
·
|
|
160
|
+
Interactive REST docs: **[api.bankregreports.com/api/v1/docs/](https://api.bankregreports.com/api/v1/docs/)**
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Pagination
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
import pandas as pd
|
|
168
|
+
|
|
169
|
+
# Iterate pages, 200 rows at a time
|
|
170
|
+
for page in brr.pages("screener", page_size=200, state="CA"):
|
|
171
|
+
process(page)
|
|
172
|
+
|
|
173
|
+
# Collect all pages into one DataFrame
|
|
174
|
+
all_banks = pd.concat(brr.pages("screener", page_size=500))
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Error handling
|
|
180
|
+
|
|
181
|
+
All errors subclass `BankRegError`. GET requests auto-retry with exponential backoff on
|
|
182
|
+
`429` and `5xx` (default 3 retries).
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
from bankregreports import (
|
|
186
|
+
BankReg, BankRegError,
|
|
187
|
+
AuthenticationError, UpgradeRequiredError, NotFoundError,
|
|
188
|
+
RateLimitError, ValidationError, ServerError,
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
try:
|
|
192
|
+
df = brr.ma_screener()
|
|
193
|
+
except UpgradeRequiredError:
|
|
194
|
+
print("Upgrade at bankregreports.com/api/")
|
|
195
|
+
except RateLimitError as e:
|
|
196
|
+
time.sleep(e.retry_after)
|
|
197
|
+
except NotFoundError:
|
|
198
|
+
print("Institution not found")
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
| Exception | HTTP | Meaning |
|
|
202
|
+
|---|---|---|
|
|
203
|
+
| `AuthenticationError` | 401 | Missing or revoked API key |
|
|
204
|
+
| `UpgradeRequiredError` | 403 | Plan doesn't cover this dataset |
|
|
205
|
+
| `NotFoundError` | 404 | Institution or resource not found |
|
|
206
|
+
| `ValidationError` | 422 | Invalid parameters |
|
|
207
|
+
| `RateLimitError` | 429 | Throttled — check `e.retry_after` |
|
|
208
|
+
| `ServerError` | 5xx | Server error (auto-retried) |
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Configuration
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
brr = bankregreports.BankReg(
|
|
216
|
+
token="brr_xxx", # or BANKREG_API_TOKEN env var
|
|
217
|
+
base_url="http://localhost:8000",
|
|
218
|
+
timeout=30,
|
|
219
|
+
max_retries=3,
|
|
220
|
+
)
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## Response format
|
|
226
|
+
|
|
227
|
+
All list-returning methods return a `pandas.DataFrame` by default (requires `pandas`
|
|
228
|
+
extra). Date columns are coerced to `datetime64`. The server response envelope is
|
|
229
|
+
available on `df.attrs["meta"]`.
|
|
230
|
+
|
|
231
|
+
Pass `as_dataframe=False` to any method for raw decoded JSON with no pandas dependency.
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## Resources
|
|
236
|
+
|
|
237
|
+
| | |
|
|
238
|
+
|---|---|
|
|
239
|
+
| Platform | [bankregreports.com](https://www.bankregreports.com) |
|
|
240
|
+
| API sign-up | [bankregreports.com/api](https://www.bankregreports.com/api/) |
|
|
241
|
+
| Swagger / REST docs | [api.bankregreports.com/api/v1/docs/](https://api.bankregreports.com/api/v1/docs/) |
|
|
242
|
+
| SDK docs | [www.bankregreports.com/api/](https://www.bankregreports.com/api/) |
|
|
243
|
+
| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
|
|
244
|
+
| Support | [admin@bankregreports.com](mailto:admin@bankregreports.com) |
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## License
|
|
249
|
+
|
|
250
|
+
Copyright © 2024–2026 BankRegReports LLC. Proprietary — see [LICENSE](./LICENSE).
|