ffiec_data_connect package

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: Union[FFIECConnection, Session], creds: WebserviceCredentials, reporting_period: Union[str, datetime], rssd_id: str, series: str, output_type='list', date_output_format='string_original') → Union[list, 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

collect_filers_on_reporting_period(session: Union[FFIECConnection, Session], creds: WebserviceCredentials, reporting_period: Union[str, datetime], output_type='list') → Union[list, 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
Returns

List of dicts or pandas 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 or pd.DataFrame

collect_filers_since_date(session: Union[FFIECConnection, Session], creds: WebserviceCredentials, reporting_period: Union[str, datetime], since_date: Union[str, datetime], output_type='list') → Union[list, 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” or “pandas”. Defaults to “list”.

Returns

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

Return type

any

collect_filers_submission_date_time(session: Union[FFIECConnection, Session], creds: WebserviceCredentials, since_date: str, reporting_period: str, output_type='list', date_output_format='string_original') → Union[list, 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” or “pandas”. Defaults to “list”.

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

Returns

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

Return type

any

collect_reporting_periods(session: Session, creds: WebserviceCredentials, series='call', output_type='list', date_output_format='string_original') → Union[list, 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 or pandas

  • date_output_format – string_original, string_yyyymmdd, or python_format

Returns

Returns a list of reporting periods from the FFIEC Webservice

Return type

list or Pandas series

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(value)

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

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(value)

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.xbrl_processor module

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

Module contents