Get Started#

This page gets you from installation to loading your first schedule.

Installation#

call-report supports Python 3.11 through 3.14 on Linux, macOS, and Windows.

pip install call-report

Reading FCA Call Report data additionally requires a dataframe library (pandas, polars, or pyarrow). Install one directly, or via an extra:

pip install "call-report[pandas]"

Key Concepts#

call-report follows a scikit-learn-style, object-oriented interface: each regulatory source has its own estimator-like entry point (for example FCACallReport). Constructing one only stores its parameters; a fetch/load-style method performs the actual work and populates trailing-underscore attributes (e.g. periods_).

Two pieces of shared vocabulary are used across every source:

  • ReportingPeriod and PeriodRange – the validated, calendar-quarter vocabulary every request and result is keyed by.

  • get_config() / set_config() – package-level configuration controlling which dataframe library every reader returns native frames of, and whether they are returned eager or lazy (see API for the full configuration API).

Every entry point also requires an explicit transport= – an injectable FCATransport describing how to resolve each requested period’s files. There is no implicit default, so it is always clear which files a given instance will read.

Quickstart#

Load a single FCA schedule for a range of quarters from a directory of already-downloaded, already-extracted release folders (one subdirectory per quarter, named after each release’s FCA zip file), using LocalDirectoryTransport:

from call_report.fca import FCACallReport
from call_report.fca.transport import LocalDirectoryTransport

report = FCACallReport(
    start="2024-03-31",
    end="2025-12-31",
    transport=LocalDirectoryTransport(data_dir="fca_data"),
)
rcb = report.load(schedule="RCB")

Alternatively, load historical quarters straight from the release zips checked into this repository’s own data/fca-call-report/ directory, with no download or manual unzipping needed, using PackagedArchiveTransport:

from call_report.fca.transport import PackagedArchiveTransport

report = FCACallReport(
    start="2024-03-31", end="2025-12-31", transport=PackagedArchiveTransport()
)
rcb = report.load(schedule="RCB")

That archive is checked into the repository but is not included in the published wheel, so PackagedArchiveTransport only works from a source checkout (e.g. an editable install for local development); a pip-installed package should use LocalDirectoryTransport instead.

load stacks the schedule across every requested period that has it, returning a native dataframe (of whichever backend is configured) with a period column identifying which quarter each row came from.

Load every schedule found across the requested range at once:

schedules = report.load_all()  # dict[FCASchedule, native dataframe]

Load the institution roster:

institutions = report.load_institutions()

Schedule metadata#

Alongside the data itself, call-report ships canonical, cross-time metadata for every FCA schedule: field names, narwhals dtypes, human-readable definitions, and the exact periods each field has actually been present for, generated from FCA’s own published archives rather than hand-maintained.

get_file_metadata() gives a schedule’s whole history, get_schema() a single quarter’s snapshot, and to_field_schema() what a release actually declared. Because all three speak the same vocabulary, checking a release against what the package expects is three lines:

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2015-03-31", end="2015-03-31", transport=PackagedArchiveTransport()
... )
>>> layout = report.get_layout(schedule="RI", period="2015-03-31")
>>> canonical = report.get_schema(schedule="RI", period="2015-03-31")
>>> layout.to_field_schema(period="2015-03-31").compare(other=canonical).is_empty
True

See Schemas and Schedule Metadata for the full treatment, including reading a diff and tracking a schedule’s drift across quarters.

Next steps#