# fdicapi
This repository contains A Python wrapper to easily retrieve data from the BankFind Suite official API from FDIC in pandas format.
## Overview
FDIC’s application programming interface (API) lets developers access FDIC’s publically available bank data.
There are eight endpoints that the FDIC has exposed to the public:
- **institutions**: Returns a list of financial institutions.
- **locations**: Returns locations/branches of financial institutions.
- **history**: Returns details on structure change events
- **financials**: Returns financial information for financial institutions
- **summary**: Returns aggregate financial and structure data, subtotaled by year, regarding finanical institutions.
- **failures**: Returns details on failed financial institutions.
- **sod**: Returns summary of deposits information for institutions
- **demographics**: Returns summary of demographic information
## Requirements
- Python 3.9 or higher.
- Requests
- Pandas
## Installation
```terminal
pip install fdicapi
```
## Endpoints
### get_institutions
Get Financial Institutions.
```python
from fdicapi.structure import get_institutions
df = get_institutions(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|--------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter for the bank search. |
| `search` | `str` | Flexible text search against institution records - currently only supporting name search. Search supports text search and fuzzy matching, as opposed to filters that are exact matches. |
| `fields` | `str` | Comma delimited list of fields to search. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
#### Returns
- `pd.DataFrame`: Return a pandas DataFrame of financial institutions.
### get_locations
Get Institution Locations.
```python
from fdicapi.structure import get_locations
df = get_locations(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|--------------|-------|-----------------------------------------------------------------------|
| `filters` | `str` | The filter for the location search. |
| `fields` | `str` | Comma delimited list of fields to search. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
#### Returns
- `pd.DataFrame`: Returns locations/branches of financial institutions.
### get_history
Get Detail on Structure Change Events.
```python
from fdicapi.history import get_history
df = get_history(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
| `search` | `str` | Flexible text search against institution records Search supports text search and fuzzy matching, as opposed to filters that are exact matches. |
| `fields` | `str` | Comma delimited list of fields to search. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
| `agg_by` | `str` | The field by which data will be aggregated. |
| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |
| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |
#### Returns
- `pd.DataFrame`: Return a pandas DataFrame of financial institutions.
### get_financials
Get Financial Information for FDIC Insured Institutions
```python
from fdicapi.financials import get_financials
df = get_financials(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|---------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
| `agg_by` | `str` | The field by which data will be aggregated. |
| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |
| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |
| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |
#### Returns
- `pd.DataFrame`: Returns financial information for financial institutions,
### get_summary
Get Historical Aggregate Data by Year.
```python
from fdicapi.historical import get_summary
df = get_summary(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|--------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
| `agg_by` | `str` | The field by which data will be aggregated. |
| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |
| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |
| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |
| `max_value` | `int` | The field by which the max value is desired. |
| `max_value_by` | `int` | The field that will be used to determine unique records, similar to a primary key (i.e. CERT, ). |
#### Returns
- `pd.DataFrame`: Returns aggregate financial and structure data, subtotaled by year, regarding finanical institutions.
### get_failures
Get detail on historical bank failures from 1934 to present.
```python
from fdicapi.failures import get_failures
df = get_failures(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
| `total_fields` | `str` | Fields to sum up (in a totals response object). Only numeric columns are valid. |
| `subtotal_fields` | `str` | The field by which data will be subtotaled (in totals response object). Only categorical values should be used. |
| `agg_by` | `str` | The field by which data will be aggregated. |
| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |
| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |
| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |
#### Returns
- `pd.DataFrame`: Returns details on failed financial institutions.
### get_sod
Get Summary of Deposits Information for FDIC Insured Institutions.
```python
from fdicapi.sod import get_sod
df = get_sod(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |
| `sort_by` | `str` | Field name by which to sort returned data. |
| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |
| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |
| `offset` | `int` | The offset of page to return. |
| `agg_by` | `str` | The field by which data will be aggregated. |
| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |
| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |
| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |
#### Returns
- `pd.DataFrame`: Returns summary of deposits information for institutions.
### get_demographics
Get Summary of Demographic Information.
```python
from fdicapi.demographics import get_demographics
df = get_demographics(**kwargs)
```
#### Keyword Arguments
| Parameter | Type | Description |
|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|
| `filters` | `str` | The filter criteria that refines the records returned. |
#### Returns
- `pd.DataFrame`: Returns summary of demographic information.
## API Documentation
- [BankFind Suite: API for Data Miners & Developers (FDIC)](https://banks.data.fdic.gov/docs/)
Raw data
{
"_id": null,
"home_page": "https://github.com/Jaldekoa/fdicapi",
"name": "fdicapi",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Jon Aldekoa",
"author_email": "jaldekoa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/c7/7bc0d90d512e9db364b1ccf238006b0b8a64afb72e5a80dd53346fbde875/fdicapi-0.0.1.tar.gz",
"platform": "Any",
"description": "# fdicapi\n\nThis repository contains A Python wrapper to easily retrieve data from the BankFind Suite official API from FDIC in pandas format.\n\n## Overview\nFDIC\u2019s application programming interface (API) lets developers access FDIC\u2019s publically available bank data. \nThere are eight endpoints that the FDIC has exposed to the public:\n\n- **institutions**: Returns a list of financial institutions.\n- **locations**: Returns locations/branches of financial institutions.\n- **history**: Returns details on structure change events\n- **financials**: Returns financial information for financial institutions\n- **summary**: Returns aggregate financial and structure data, subtotaled by year, regarding finanical institutions.\n- **failures**: Returns details on failed financial institutions.\n- **sod**: Returns summary of deposits information for institutions\n- **demographics**: Returns summary of demographic information\n\n## Requirements\n- Python 3.9 or higher.\n- Requests\n- Pandas\n\n## Installation\n```terminal\npip install fdicapi\n```\n\n## Endpoints\n### get_institutions\nGet Financial Institutions.\n\n```python\nfrom fdicapi.structure import get_institutions\ndf = get_institutions(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|--------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter for the bank search. |\n| `search` | `str` | Flexible text search against institution records - currently only supporting name search. Search supports text search and fuzzy matching, as opposed to filters that are exact matches. |\n| `fields` | `str` | Comma delimited list of fields to search. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n\n#### Returns\n- `pd.DataFrame`: Return a pandas DataFrame of financial institutions.\n\n### get_locations\nGet Institution Locations.\n\n```python\nfrom fdicapi.structure import get_locations\ndf = get_locations(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|--------------|-------|-----------------------------------------------------------------------|\n| `filters` | `str` | The filter for the location search. |\n| `fields` | `str` | Comma delimited list of fields to search. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n\n#### Returns\n- `pd.DataFrame`: Returns locations/branches of financial institutions.\n\n\n### get_history\nGet Detail on Structure Change Events.\n\n```python\nfrom fdicapi.history import get_history\ndf = get_history(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n| `search` | `str` | Flexible text search against institution records Search supports text search and fuzzy matching, as opposed to filters that are exact matches. |\n| `fields` | `str` | Comma delimited list of fields to search. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n| `agg_by` | `str` | The field by which data will be aggregated. |\n| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |\n| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |\n\n#### Returns\n- `pd.DataFrame`: Return a pandas DataFrame of financial institutions.\n\n\n### get_financials\nGet Financial Information for FDIC Insured Institutions\n\n```python\nfrom fdicapi.financials import get_financials\ndf = get_financials(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|---------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n| `agg_by` | `str` | The field by which data will be aggregated. |\n| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |\n| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |\n| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |\n\n#### Returns\n- `pd.DataFrame`: Returns financial information for financial institutions,\n\n\n### get_summary\nGet Historical Aggregate Data by Year.\n\n```python\nfrom fdicapi.historical import get_summary\ndf = get_summary(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|--------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n| `agg_by` | `str` | The field by which data will be aggregated. |\n| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |\n| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |\n| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |\n| `max_value` | `int` | The field by which the max value is desired. |\n| `max_value_by` | `int` | The field that will be used to determine unique records, similar to a primary key (i.e. CERT, ). |\n\n#### Returns\n- `pd.DataFrame`: Returns aggregate financial and structure data, subtotaled by year, regarding finanical institutions.\n\n\n### get_failures\nGet detail on historical bank failures from 1934 to present.\n\n```python\nfrom fdicapi.failures import get_failures\ndf = get_failures(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n| `total_fields` | `str` | Fields to sum up (in a totals response object). Only numeric columns are valid. |\n| `subtotal_fields` | `str` | The field by which data will be subtotaled (in totals response object). Only categorical values should be used. |\n| `agg_by` | `str` | The field by which data will be aggregated. |\n| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |\n| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |\n| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |\n\n#### Returns\n- `pd.DataFrame`: Returns details on failed financial institutions.\n\n\n### get_sod\nGet Summary of Deposits Information for FDIC Insured Institutions.\n\n```python\nfrom fdicapi.sod import get_sod\ndf = get_sod(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n| `fields` | `str` | Comma delimited list of fields with quarterly financial data to return. |\n| `sort_by` | `str` | Field name by which to sort returned data. |\n| `sort_order` | `str` | Indicator if ascending (ASC) or descending (DESC). |\n| `limit` | `int` | The number of records to return. Default is 10 and maximum is 10,000. |\n| `offset` | `int` | The offset of page to return. |\n| `agg_by` | `str` | The field by which data will be aggregated. |\n| `agg_term_fields` | `str` | The field(s) for which aggregations will be counted for each unique term. |\n| `agg_sum_fields` | `str` | The field(s) for which aggregations will be summed or aggregated. |\n| `agg_limit` | `int` | The limit on how many aggregated results will be displayed. |\n\n#### Returns\n- `pd.DataFrame`: Returns summary of deposits information for institutions.\n\n\n### get_demographics\nGet Summary of Demographic Information.\n\n```python\nfrom fdicapi.demographics import get_demographics\ndf = get_demographics(**kwargs)\n```\n\n#### Keyword Arguments\n| Parameter | Type | Description |\n|-------------------|-------|-----------------------------------------------------------------------------------------------------------------|\n| `filters` | `str` | The filter criteria that refines the records returned. |\n\n#### Returns\n- `pd.DataFrame`: Returns summary of demographic information.\n\n## API Documentation\n- [BankFind Suite: API for Data Miners & Developers (FDIC)](https://banks.data.fdic.gov/docs/)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python wrapper to easily retrieve data from the BankFind Suite official API from FDIC in pandas format.",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/Jaldekoa/fdicapi"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "57469da9dffe61283c208f4a4dc37025b8727928337c48965529869f4dd06a4b",
"md5": "9271e8b506f00d572e6496e9628436cf",
"sha256": "e35ae8a78299860eebfe083caaa8dd19571edf0ed25d302611e8517e8db129ed"
},
"downloads": -1,
"filename": "fdicapi-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9271e8b506f00d572e6496e9628436cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9600,
"upload_time": "2024-09-17T01:15:10",
"upload_time_iso_8601": "2024-09-17T01:15:10.627447Z",
"url": "https://files.pythonhosted.org/packages/57/46/9da9dffe61283c208f4a4dc37025b8727928337c48965529869f4dd06a4b/fdicapi-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50c77bc0d90d512e9db364b1ccf238006b0b8a64afb72e5a80dd53346fbde875",
"md5": "74fd55308b667d4c235f0bc4588d51f2",
"sha256": "874ee22c082155721f253568f06e8b5510a9eec1c14982f16616851e6735ca87"
},
"downloads": -1,
"filename": "fdicapi-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "74fd55308b667d4c235f0bc4588d51f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7503,
"upload_time": "2024-09-17T01:15:12",
"upload_time_iso_8601": "2024-09-17T01:15:12.089808Z",
"url": "https://files.pythonhosted.org/packages/50/c7/7bc0d90d512e9db364b1ccf238006b0b8a64afb72e5a80dd53346fbde875/fdicapi-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-17 01:15:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jaldekoa",
"github_project": "fdicapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.23.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"68.2"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.4"
]
]
}
],
"lcname": "fdicapi"
}
JSON
