bolster.data_sources.ons_cpi

ONS UK inflation indices (CPI, CPIH, RPI).

Wraps the Office for National Statistics (ONS) open time-series API to provide standardised access to the headline UK inflation measures:

• CPIH — Consumer Prices Index including owner-occupiers’ housing costs

• CPI — Consumer Prices Index

• RPI — Retail Prices Index (longest run, back to 1948)

Each measure is available both as a 12-month annual rate (%) and as a price index. Data is published at monthly, quarterly and annual resolutions.

This is the first of three macroeconomic context modules and emits a fixed output schema so that inflation, and the other macro modules, can be joined and resampled against one another:

Column	Description
date	datetime64[ns] period-start (Jan 2024 -> 2024-01-01, Q1 2024 -> 2024-01-01, year 2024 -> 2024-01-01)
year	int calendar year
quarter	str “Q1”..”Q4”, or pd.NA for annual/monthly
month	int 1-12, or pd.NA for quarterly/annual
resolution	str “annual” | “quarterly” | “monthly”
series	str ONS series code, e.g. “D7G7”
value	float observation value
unit	str e.g. “%” or “Index 2015=100”
geography	str always “UK”
source	str always “ONS”

Source:

https://www.ons.gov.uk/economy/inflationandpriceindices

Example

>>> from bolster.data_sources import ons_cpi
>>> df = ons_cpi.get_series("D7G7", resolution="annual")  
>>> sorted(df.columns)  
['date', 'geography', 'month', 'quarter', 'resolution', 'series', 'source', 'unit', 'value', 'year']

Attributes

logger
BASE_URL
GEOGRAPHY
SOURCE
SCHEMA_COLUMNS
SERIES

Exceptions

ONSDataError	Base exception for ONS data errors.
ONSValidationError	Raised when a DataFrame fails validate_data().

Functions

get_series(code[, resolution, force_refresh])	Fetch a single ONS inflation series at a given resolution.
get_latest_data([resolution, force_refresh])	Fetch all supported series at a given resolution, concatenated.
validate_data(df)	Validate that a DataFrame conforms to the macroeconomic schema.

Module Contents

bolster.data_sources.ons_cpi.logger

bolster.data_sources.ons_cpi.BASE_URL = 'https://www.ons.gov.uk/economy/inflationandpriceindices/timeseries/{code}/data'

bolster.data_sources.ons_cpi.GEOGRAPHY = 'UK'

bolster.data_sources.ons_cpi.SOURCE = 'ONS'

bolster.data_sources.ons_cpi.SCHEMA_COLUMNS = ['date', 'year', 'quarter', 'month', 'resolution', 'series', 'value', 'unit', 'geography', 'source']

bolster.data_sources.ons_cpi.SERIES

exception bolster.data_sources.ons_cpi.ONSDataError

Bases: Exception

Base exception for ONS data errors.

Initialize self. See help(type(self)) for accurate signature.

exception bolster.data_sources.ons_cpi.ONSValidationError

Bases: ONSDataError

Raised when a DataFrame fails validate_data().

Initialize self. See help(type(self)) for accurate signature.

bolster.data_sources.ons_cpi.get_series(code, resolution='monthly', force_refresh=False)

Fetch a single ONS inflation series at a given resolution.

Parameters:

• code (str) – ONS series code (case-insensitive). One of SERIES.

• resolution (str) – “monthly” (default), “quarterly” or “annual”.

• force_refresh (bool) – Bypass the page cache and re-download.

Returns:

DataFrame conforming to SCHEMA_COLUMNS, sorted by date.

Raises:

• ValueError – If code or resolution is not recognised.

• ONSDataError – If the underlying API request fails.

Return type:

pandas.DataFrame

Example

>>> df = get_series("D7G7", resolution="annual")  
>>> df.iloc[-1][["series", "unit", "geography"]].tolist()  
['D7G7', '%', 'UK']

bolster.data_sources.ons_cpi.get_latest_data(resolution='monthly', force_refresh=False)

Fetch all supported series at a given resolution, concatenated.

Parameters:

• resolution (str) – “monthly” (default), “quarterly” or “annual”.

• force_refresh (bool) – Bypass the page cache and re-download each series.

Returns:

DataFrame conforming to SCHEMA_COLUMNS containing every code in SERIES, sorted by series then date.

Raises:

ValueError – If resolution is not recognised.

Return type:

pandas.DataFrame

Example

>>> df = get_latest_data(resolution="annual")  
>>> sorted(df["series"].unique())  
['CHAW', 'CZBH', 'D7BT', 'D7G7', 'L522', 'L55O']

bolster.data_sources.ons_cpi.validate_data(df)

Validate that a DataFrame conforms to the macroeconomic schema.

Checks performed:

• All SCHEMA_COLUMNS are present.

• At least one row is present.

• geography is exclusively “UK” and source exclusively “ONS”.

• resolution only contains known values.

• value is numeric with no nulls.

Parameters:

df (pandas.DataFrame) – DataFrame to validate.

Returns:

True if all checks pass.

Raises:

ONSValidationError – If any check fails.

Return type:

bool

Example

>>> df = get_series("D7G7", resolution="annual")  
>>> validate_data(df)  
True