ffiec_data_connect package

Submodules

ffiec_data_connect.constants module

Constant values utilized for data collection and other purposes.

This module contains constant values that are unlikely to change, but need to be referenced by other modules.

class WebserviceConstants

Bases: object

The URL endpoint for the FFIEC SOAP-based webservice.

base_url = 'https://cdr.ffiec.gov/Public/PWS/WebServices/RetrievalService.asmx?WSDL'

ffiec_data_connect.credentials module

Methods to utilize for inputting credentials for the FFIEC data connection.

This module provides secure methods for inputting credentials for the FFIEC webservice data connection.

Credentials may be input via environment variables, or passing them as arguments into the class structure. Wherever possible, the credentials should not be stored in source code.

class CredentialType(*values)

Bases: Enum

Enumerated values that represent the methods through which credentials are provided to the FFIEC webservice via the package.

Parameters:

Enum (integer) – Integer that represents the credential input method

NO_CREDENTIALS = 0
SET_FROM_ENV = 2
SET_FROM_INIT = 1
class WebserviceCredentials(username=None, password=None)

Bases: object

The WebserviceCredentials class. This class is used to store the credentials for the FFIEC webservice.

Parameters:

  • username (str, optional) – FFIEC Webservice username. Optional: If not provided, the credentials will be set from the environment variable FFIEC_USERNAME

  • password (str, optional) – FFIEC Webservice password. Optional: If not provided, the credentials will be set from the environment variable FFIEC_PASSWORD

Returns:

An instance of the WebserviceCredentials class.

Return type:

WebserviceCredentials

property password: str

Returns the password from the WebserviceCredentials instance.

Returns:

the password stored in the WebserviceCredentials instance

Return type:

str

return_all_services_and_methods(session: Session) → None

Returns all services and methods for the FFIEC Webservice.

Parameters:

session (requests.Session) – the connection to the FFIEC Webservice

test_credentials(session: Session) → bool

Test the credentials with the FFIEC Webservice to determine if they are valid and accepted.

Note: The session argument can be generated directly from requests, or
using the helper class FFIECConnection
Parameters:

session (requests.Session) – the connection to test the credentials

Returns:

True if the credentials are valid, False otherwise

Return type:

bool

Raises:

  • ValueError – if the credentials are not set

  • Exception – Other unspecified errors

property username: str

Returns the username from the WebserviceCredentials instance.

Returns:

the username stored in the WebserviceCredentials instance

Return type:

str

ffiec_data_connect.datahelpers module

Internal functions to assist with processing results from the Webservice

ffiec_data_connect.exceptions module

Descriptive exceptions for the ffiec_data_connect package

exception NoDataError

Bases: Exception

ffiec_data_connect.ffiec_connection module

Wrapper to establish requests.Session and set proxy server values if needed

An instance of this class may be substituted for an instance requests.Session class.

class FFIECConnection

Bases: object

Creates a FFIECConnection object, which may include proxy server connection parameters

property proxy_host: str

Returns the hostname of the proxy server

Returns:

The hostname of the proxy server

Return type:

str

property proxy_password: str

Get the optional proxy password

Returns:

the password of the proxy server

Return type:

str

property proxy_port: int

Get the optional proxy port

Returns:

the proxy port

Return type:

int

property proxy_protocol: int

Returns the protocol of the proxy server

Returns:

the protocol of the proxy server

Return type:

int

property proxy_user_name: str

Get the optional proxy username

Returns:

the proxy username

Return type:

str

property session: Session

Returns the requests.Session object * Note that this property may be utilized for methods in the methods module.

This session property is automatically generated when the FFIECConnection object is created.

Returns:

the requests.Session object

Return type:

requests.Session

test_connection(url: str = 'https://google.com') → bool

Tests a connection, using the proxy server if one is not set

Note: This method tests if a web page on the public internet (not the FFIEC webservice) is accessible using this library, through the proxy server.

We do not yet test access to the Webservice, because a user name and password is needed to access the Webservice, which is outside the scope of this module.

An alternative web site may be selected in lieu of google.com, using the url parameter.

property use_proxy: bool

Get the optional proxy flag

Returns:

the proxy flag (True if proxy is used, False if not)

Return type:

bool

class ProxyProtocol(*values)

Bases: Enum

Enumerated values that represent the proxy protocol options

Parameters:

Enum (ProxyProtocol) – Enumerated value for HTTP or HTTPS

HTTP = 0
HTTPS = 1

ffiec_data_connect.methods module

Methods that wrap the FFIEC Webservice API

The methods contained in this module are utilized to call and collect data from the FFIEC Webservice API.

collect_data(session: FFIECConnection | Session, creds: WebserviceCredentials, reporting_period: str | datetime, rssd_id: str, series: str, output_type='list', date_output_format='string_original') → list | DataFrame | DataFrame

Return time series data from the FFIEC webservice for a given reporting period and RSSD ID.

Translates the input reporting period to a FFIEC-formatted date Transforms the output to a pandas dataframe if output_type is ‘pandas’, otherwise returns a list

Valid arguments for the ``reporting_period` argument:

  • mm/dd/yyyy

  • yyyy-mm-dd

  • yyyymmdd

  • a python datetime object

  • For the above types, the date msut be the last day in the quarter (e.g. March 31, June 30, September 30, or December 31)

  • #Qyyyy, where # is the quarter number and yyyy is the year.

Parameters:

  • session (FFIECConnection or requests.Session) – The requests session object to use for the request.

  • creds (WebserviceCredentials) – The credentials to use for the request.

  • reporting_period (str or datetime) – Reporting period.

  • rssd_id (str) – The RSSD ID of the entity for which you want to retrieve data.

  • series (str) – call or ubpr

  • output_type (str) – list or pandas

  • date_output_format (str) – string_original, string_yyyymmdd, or python_format

Returns:

Returns either a list of dicts or a pandas DataFrame

Return type:

list or pandas

Raises:

  • ValueError – If input arguments are invalid or if no data is returned.

  • Exception – For other unexpected errors.

Example

>>> df = collect_data(session, creds, '2024-12-31', '12345', 'call', output_type='polars')
collect_filers_on_reporting_period(session: FFIECConnection | Session, creds: WebserviceCredentials, reporting_period: str | datetime, output_type='list') → list | DataFrame | DataFrame

Retrieves the Financial Institutions in a Panel of Reporters for a given reporting period. Note that this function only reports on Call Report filings, not UBPR filings.

Valid arguments for the ``reporting_period` argument:

  • mm/dd/yyyy

  • yyyy-mm-dd

  • yyyymmdd

  • a python datetime object

  • For the above types, the date must be the last day in the quarter (e.g. March 31, June 30, September 30, or December 31)

  • #Qyyyy, where # is the quarter number and yyyy is the year.

Parameters:

  • session (ffiec_connection.FFIECConnection or requests.Session) – The requests session object to use for the request.

  • creds (credentials.WebserviceCredentials) – The credentials to use for the request.

  • reporting_period (str or datetime) – The reporting period to use for the request.

  • output_type (str, optional) – “list”, “pandas”, or “polars”. Defaults to “list”.

Returns:

List of dicts, pandas DataFrame, or Polars DataFrame containing the rssd id of the filer, and the following fields: “id_rssd”, “fdic_cert_number”, “occ_chart_number”, “ots_dock_number”, “primary_aba_rout_number”, “name”, “state”, “city”, “address”, “filing_type”, “has_filed_for_reporting_period”

Return type:

list, pd.DataFrame, or pl.DataFrame

collect_filers_since_date(session: FFIECConnection | Session, creds: WebserviceCredentials, reporting_period: str | datetime, since_date: str | datetime, output_type='list') → list | Series | Series

Retrieves the ID RSSDs of the reporters who have filed after a given date for a given reporting period. Note that this function only reports on Call Report filings, not UBPR filings.

Valid arguments for the ``since_date` argument:

  • mm/dd/yyyy

  • yyyy-mm-dd

  • yyyymmdd

  • a python datetime object

Valid arguments for the ``reporting_period` argument:

  • all of the above, as long as the date is the last day in the quarter (e.g. March 31, June 30, September 30, or December 31)

  • #Qyyyy, where # is the quarter number and yyyy is the year.

Parameters:

  • session (FFIECConnection or requests.Session) – The requests session object to use for the request.

  • creds (WebserviceCredentials) – The credentials to use for the request.

  • since_date (str or datetime) – The date to use for the request. May be in the format of ‘YYYY-MM-DD’, ‘YYYYMMDD’, ‘MM/DD/YYYY’, or a python datetime object.

  • output_type (str, optional) – “list”, “pandas”, or “polars”. Defaults to “list”.

Returns:

Returns either a list of dicts, a pandas Series, or a Polars Series comprising the ID RSSDs of the reporters who have filed after a given date for a given reporting period.

Return type:

list, Pandas Series, or Polars Series

collect_filers_submission_date_time(session: FFIECConnection | Session, creds: WebserviceCredentials, since_date: str | datetime, reporting_period: str | datetime, output_type='list', date_output_format='string_original') → list | DataFrame | DataFrame

Retrieves the ID RSSDs and DateTime of the reporters who have filed after a given date for a given reporting period. Note that this function only reports on Call Report filings, not UBPR filings.

Note on date_output_format:

  • string_original is the default output format, and is the format that is used by the FFIEC webservice: mm/dd/yyyy

  • string_yyyymmdd is the date in yyyymmdd format

  • python_format is the date in python datetime format

Parameters:

  • session (ffiec_connection.FFIECConnection or requests.Session) – The requests session object to use for the request.

  • creds (WebserviceCredentials or requests.Session) – The credentials to use for the request.

  • since_date (str or datetime) – The date to use for the request. May be in the format of ‘YYYY-MM-DD’, ‘YYYYMMDD’, ‘MM/DD/YYYY’, or a python datetime object.

  • reporting_period (str or datetime) – The reporting period to use for the request (e.g. “2020-03-21”). Note that the date must be in the format of “YYYY-MM-DD”, “YYYYMMDD”, “MM/DD/YYYY”, #QYYYY or a python datetime object, with the month and date set to March 31, June 30, September 30, or December 31.

  • output_type (str, optional) – “list”, “pandas”, or “polars”. Defaults to “list”.

  • date_output_format (str, optional) – string_original or python_datetime. Defaults to “string_original”.

Returns:

List of dicts, pandas DataFrame, or Polars DataFrame containing the rssd id of the filer, and the submission date and time, in Washington DC timezone.

Return type:

list, Pandas DataFrame, or Polars DataFrame

collect_reporting_periods(session: Session, creds: WebserviceCredentials, series='call', output_type='list', date_output_format='string_original') → list | Series | Series

Returns list of reporting periods available for access via the FFIEC webservice

Note on date_output_format:

  • string_original is the default output format, and is the format that is used by the FFIEC webservice: mm/dd/yyyy

  • string_yyyymmdd is the date in yyyymmdd format

  • python_format is the date in python datetime format

Parameters:

  • session (requests.Session) – The requests session object to use for the request.

  • creds (credentials.WebserviceCredentials) – The credentials to use for the request.

  • series (str, optional) – call or ubpr

  • output_type (str) – list, pandas, or polars

  • date_output_format – string_original, string_yyyymmdd, or python_format

Returns:

Returns a list of reporting periods from the FFIEC Webservice

Return type:

list, Pandas Series, or Polars Series

ffiec_data_connect.xbrl_processor module

Internal functions used to process XBRL data received from the FFIEC Webservice

Module contents