okama-macro

Installation · Quick start · Available series · Data quality · Documentation · Contributing

Normalized CPI inflation and central-bank rate series for Python, built for the okama project and available as a standalone package.

okama-macro consolidates official macroeconomic data clients behind one installable package, a shared HTTP/DataFrame layer, and a consistent public API.

Highlights

• One API — discover series with list_series() and fetch them with get().
• Consistent output — every public series uses decimal fractions, an ascending DatetimeIndex, float values, and a stable series name.
• Broad coverage — CPI and policy-rate series across the United States, Hong Kong, India, China, the United Kingdom, Israel, and the euro area.
• Raw-source access — use the underlying clients when source-native units and shapes are required.
• Source-aware transport — shared retries, proxy support, secret redaction, and compatibility handling for sources with specialized TLS or User-Agent requirements.

Installation

python -m pip install okama-macro

Requires Python ≥ 3.11. Runs on both pandas 2.x and 3.x.

Quick start

from okama_macro import get, list_series

# Discover the supported public keys.
keys = list_series()

# Fetch a normalized rate series for a date window.
deposit_rate = get(
    "EU_DFR.RATE",
    first_date="2024-01-01",
    last_date="2024-12-31",
)

# Monthly m/m inflation as a decimal fraction:
us_inflation = get("USD.INFL", first_date="2024-01-01")

Each get() call returns a pandas.Series. For example, a 3.62% rate is represented as 0.0362, not 3.62.

USD.INFL and US_EFFR.RATE require a FRED API key in the FRED_API_KEY environment variable.

Data contract

Every series returned by get() obeys the same contract, so callers never special-case a source:

• Decimal fractions — m/m inflation 0.0042, a rate 0.0525 (never percent, never an index level).
• CPI series are monthly, stamped on the first of the month, derived from the source's index via pct_change() (base-invariant).
• Rate series normally carry observations only — no padding. Forward-fill to a daily grid on the consumer side if you need one. UK_BR.RATE is the documented exception: the Bank of England source publishes change dates, and the client safely forward-fills them into a daily series.
• Ascending DatetimeIndex, float dtype, and Series.name == key.

get() raises ValueError for an unknown key (listing the known ones); list_series() returns the available keys, sorted.

Available series

Raw source clients

Each source also exposes its raw client under okama_macro.sources.*, returning data as the agency publishes it (CPI index levels, rates in percent) — use these only if you need the unnormalised series; prefer get() otherwise.

from okama_macro.sources import (
    bis, boe, boi, censtatd, cfets, ecb, fred, hkma, mospi, nbsc, ons, rbi
)

hkma.get_base_rate()          # percent, daily
censtatd.get_composite_cpi()  # CPI index level, monthly

Configuration (environment)

Data provenance and limitations

• Public series are fetched from the publishers named in the table above and normalized by okama_macro.registry; raw clients preserve source-native units and shapes.
• Publishers can revise historical observations, change endpoint behavior, or publish on different schedules. Results therefore reflect the data available from the upstream source at request time.
• Historical depth and observation frequency are source-specific. Do not assume that every country or rate has the same start date or update cadence.
• Malformed and unexpectedly empty upstream responses fail loudly. The registry does not silently replace one publisher with another unless composition is an explicit, documented rule.
• For audit-sensitive use, compare critical observations with the original publisher and consult the recorded data-quality audits below.

Data quality

Material parser changes and newly consumed series are checked against independent sources when a comparable mirror exists. The recorded audits describe the comparison method, coverage, and known limitations:

• China CPI
• China Loan Prime Rates
• ECB key rates
• Israel CPI and policy rate
• UK CPIH
• UK Bank Rate

Architecture

okama_macro/
├── __init__.py        # public API: get(), list_series()
├── registry.py        # key -> normalised Series (the contract)
├── _http.py           # shared Session: retry/back-off, proxy, browser UA,
│                       #   legacy-TLS, secret redaction
├── _frame.py          # DataFrame/Series shaping helpers
└── sources/           # one client per source (bis, boe, boi, censtatd, cfets,
                        #   ecb, fred, hkma, mospi, nbsc, ons, rbi)

Two layers: thin sources (data as published, on the shared _http) and a registry that normalises each key to the contract above.

The package replaces separate per-source clients and duplicated modules that previously lived across the okama ecosystem. The rationale and migration history are tracked in mbk-dev/okama-API#41.

Contributing

Set up a local development checkout with Poetry:

git clone https://github.com/mbk-dev/okama-macro.git
cd okama-macro
poetry install
poetry run pytest -q
poetry run ruff check .
poetry build

CI runs the suite and lint on Python 3.11, 3.12, 3.13 and 3.14. Keep executable changes covered by tests and do not commit poetry.lock; the full development workflow is documented in CONTRIBUTING.md.

License

okama-macro is distributed under the MIT License.