Package {fdic}

Title: Interface to 'BankFind Suite API'
Version: 0.1.2
Description: Provides a convenient interface to the 'BankFind Suite API' made available by the Federal Deposit Insurance Corporation (FDIC). Contains functions to retrieve data related to qualitative institution information, branch and office locations, Summary of Deposit reporting, financial information, failed financial institutions, structural change events, historic aggregate industry data, and demographics information. See https://api.fdic.gov/banks/docs/ for the official 'BankFind Suite API' documentation published by the FDIC.
License: MIT + file LICENSE
Encoding: UTF-8
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
Depends: R (≥ 4.1)
LazyData: true
Imports: cli, httr2, tibble
URL: https://github.com/ketchbrookanalytics/fdic, https://ketchbrookanalytics.github.io/fdic/
BugReports: https://github.com/ketchbrookanalytics/fdic/issues
Config/roxygen2/version: 8.0.0
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-09-03 19:46:41 UTC; root
Author: Dylan Hughes [aut, cre], Michael Thomas [aut], Ketchbrook Analytics [cph, fnd]
Maintainer: Dylan Hughes <dhughes@ketchbrookanalytics.com>
Repository: CRAN
Date/Publication: 2026-09-12 14:50:02 UTC

Field definitions for the FDIC BankFind Suite ⁠/demographics⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/demographics⁠ endpoint via get_demographics().

Usage

fdic_demographics

Format

A data frame with 54 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_demographics() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/failures⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/failures⁠ endpoint via get_failures().

Usage

fdic_failures

Format

A data frame with 21 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_failures() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/financials⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/financials⁠ endpoint via get_financials().

Usage

fdic_financials

Format

A data frame with 2,377 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_financials() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/history⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/history⁠ endpoint via get_history().

Usage

fdic_history

Format

A data frame with 176 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_history() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/institutions⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/institutions⁠ endpoint via get_institutions().

Usage

fdic_institutions

Format

A data frame with 151 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_institutions() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/locations⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/locations⁠ endpoint via get_locations().

Usage

fdic_locations

Format

A data frame with 35 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_locations() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/sod⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/sod⁠ endpoint via get_sod().

Usage

fdic_sod

Format

A data frame with 82 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_sod() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Field definitions for the FDIC BankFind Suite ⁠/summary⁠ endpoint

Description

A data frame describing the fields available when querying the ⁠/summary⁠ endpoint via get_summary().

Usage

fdic_summary

Format

A data frame with 203 rows and 4 columns:

field

Field name, as passed to the fields or sort_by arguments.

title

Human-readable title for the field.

description

Extended description of the field, where available.

type

Data type of the field ("string" or "number").

Note

This dataset reflects the API field definitions provided by the FDIC at the time the package was built. The FDIC API may have added, removed, or renamed fields since then. To confirm which fields are currently available, call get_summary() with limit = 1 and no fields argument.

Source

https://api.fdic.gov/banks/docs/

Retrieve Summary of Demographic Data for FDIC-Insured Institutions

Description

Queries the ⁠/demographics⁠ endpoint of the FDIC BankFind Suite API, returning demographic data for FDIC-insured financial institutions.

Usage

get_demographics(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing demographic data for FDIC-insured institutions, with one row per institution.

Examples


# Return demographic data for a specific institution
suppressMessages(get_demographics(filters = "CERT:10002"))

# Return specific fields only
suppressMessages(get_demographics(
  fields = c("CERT", "OFFSTATE", "OFFTOT", "REPDTE"),
  limit = 5
))

# Sort by report date in descending order
suppressMessages(get_demographics(
  fields = c("CERT", "OFFTOT", "REPDTE"),
  sort_by = "REPDTE",
  descending = TRUE,
  limit = 5
))

Retrieve Historic Bank Failure Data

Description

Queries the ⁠/failures⁠ endpoint of the FDIC BankFind Suite API, returning data for failed financial institutions from 1934 to present.

Usage

get_failures(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing bank failure data for FDIC-insured institutions, with one row per failure event.

Examples


# Return the 5 most recent bank failures
suppressMessages(get_failures(
  sort_by = "FAILDATE",
  descending = TRUE,
  limit = 5
))

# Filter to failures in a single state
suppressMessages(get_failures(
  filters = "PSTALP:NY",
  limit = 5
))

# Return specific fields only
suppressMessages(get_failures(
  fields = c("CERT", "FAILDATE", "NAME", "PSTALP"),
  limit = 5
))

Retrieve Financial Data for FDIC-Insured Institutions

Description

Queries the ⁠/financials⁠ endpoint of the FDIC BankFind Suite API, returning financial data for FDIC-insured financial institutions.

Usage

get_financials(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. Defaults to all available fields if not specified. Run fdic_financials$field for valid values.

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000. Note: when more than 250 fields are requested, the maximum is 500.

Details

The ⁠/financials⁠ endpoint returns one row per institution per reporting period (quarter). Requesting more than 250 fields reduces the maximum allowed limit to 500 records; exceeding this will raise an error.

Value

A tibble containing financial data for FDIC-insured institutions, with one row per institution per reporting period.

Examples


# Return key financial fields for institutions in New York
suppressMessages(get_financials(
  filters = "STALP:NY",
  fields = c("ASSET", "CERT", "NETINC", "REPDTE"),
  limit = 5
))

# Sort by total assets descending
suppressMessages(get_financials(
  fields = c("ASSET", "CERT"),
  sort_by = "ASSET",
  descending = TRUE,
  limit = 5
))

Retrieve Data on Structural Change Events for FDIC-Insured Institutions

Description

Queries the ⁠/history⁠ endpoint of the FDIC BankFind Suite API, returning data for structural change events for FDIC-insured financial institutions.

Usage

get_history(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing structural change events for FDIC-insured institutions, with one row per structural change event.

Examples


# Return the 5 most recent structural change events
suppressMessages(get_history(
  sort_by = "PROCDATE",
  descending = TRUE,
  limit = 5
))

# Return specific fields only
suppressMessages(get_history(
  fields = c("CERT", "CHANGECODE", "CHANGECODE_DESC", "PROCDATE"),
  limit = 5
))

Retrieve Financial Institutions

Description

Queries the ⁠/institutions⁠ endpoint of the FDIC BankFind Suite API, returning FDIC-insured financial institution data.

Usage

get_institutions(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing FDIC-insured institution information, with one row per institution.

Examples


# Return active institutions in New York
suppressMessages(get_institutions(
  filters = "STALP:NY AND ACTIVE:1",
  limit = 5
))

# Return the 5 largest institutions by total assets
suppressMessages(get_institutions(
  fields = c("ASSET", "CERT", "NAME", "STALP"),
  sort_by = "ASSET",
  descending = TRUE,
  limit = 5
))

Retrieve Financial Institution Locations

Description

Queries the ⁠/locations⁠ endpoint of the FDIC BankFind Suite API, returning location data for FDIC-insured financial institutions.

Usage

get_locations(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing location data for FDIC-insured institutions, with one row per institution location.

Examples


# Return branch locations in New York
suppressMessages(get_locations(
  filters = "STALP:NY",
  limit = 5
))

# Return specific fields only
suppressMessages(get_locations(
  filters = "STALP:NY",
  fields = c("ADDRESS", "CERT", "CITY", "STALP"),
  limit = 5
))

Retrieve Summary of Deposit (SOD) Data for FDIC-Insured Institutions

Description

Queries the ⁠/sod⁠ endpoint of the FDIC BankFind Suite API, returning summary of deposit data for FDIC-insured financial institutions.

Usage

get_sod(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing summary of deposits data for FDIC-insured institutions, with one row per institution location.

Examples


# Return Summary of Deposit data for institutions in New York
suppressMessages(get_sod(
  filters = "STALP:NY",
  limit = 5
))

# Return specific fields, sorted by total assets descending
suppressMessages(get_sod(
  filters = "STALP:NY",
  fields = c("ASSET", "CERT", "CITY", "YEAR"),
  sort_by = "ASSET",
  descending = TRUE,
  limit = 5
))

Retrieve Historical Aggregate Data by Year for FDIC-Insured Institutions

Description

Queries the ⁠/summary⁠ endpoint of the FDIC BankFind Suite API, returning aggregate data by bank type, state, quarter, and year for FDIC-insured financial institutions.

Usage

get_summary(
  api_key = Sys.getenv("FDIC_API_KEY"),
  filters = NULL,
  fields = NULL,
  sort_by = NULL,
  descending = FALSE,
  limit = 10000
)

Arguments

api_key

(String) Your FDIC API key. Required: the FDIC does not accept unauthenticated requests. Defaults to the value of the FDIC_API_KEY environment variable. Register for a free personal key (1,000 req/hr) at https://api.data.gov/signup/.

filters

(String) An optional Elasticsearch query string to filter results. All field names and values must be uppercase.

fields

(String or Character vector) Fields to include in the response. An ID column is always present, regardless of the fields requested. To retrieve the most recently published API definition for an endpoint, replace the get_ prefix in the function name with fdic_ (e.g., ⁠get_{endpoint}()⁠ to ⁠fdic_{endpoint}()⁠).

sort_by

(String) Field name to sort results by. Defaults to the API default sort order for this endpoint.

descending

(Logical) Should results be sorted in descending order? Only applies when sort_by is specified. Defaults to FALSE.

limit

(Integer) Number of records to return. Must be between 1 and 10,000. Defaults to 10,000.

Value

A tibble containing historic aggregate financial and structure data regarding financial institutions, with one row per quarter and year.

Examples


# Return summary data for each bank type, state, quarter, and year
suppressMessages(get_summary(
  fields = c("ASSET", "BANKS", "BRANCHES", "CALLYM", "NETINC"),
  limit = 5
))

# Return summary data sorted by reporting period descending
suppressMessages(get_summary(
  fields = c("ASSET", "BANKS", "CALLYM", "YEAR"),
  sort_by = "CALLYM",
  descending = TRUE,
  limit = 5
))

Handle missing API key without throwing an error for unit testing purposes

Description

Handle missing API key without throwing an error for unit testing purposes

Usage

no_creds_available(api_key = Sys.getenv("FDIC_API_KEY"))

Arguments

api_key

(String) The API key for authenticating against the FDIC API

Details

Intended for internal use.

Value

(Logical) FALSE if a non-empty api_key has been supplied; otherwise TRUE.