bolster.data_sources.ni_house_price_index

Northern Ireland House Price Index Data.

Provides access to quarterly house price index, standardised prices, and sales volumes for Northern Ireland with breakdowns by: - Property type (Detached, Semi-Detached, Terrace, Apartment) - New vs Existing dwellings - Local Government District (11 LGDs) - Urban vs Rural areas

Data Source:

Publication Page: https://www.finance-ni.gov.uk/publications/ni-house-price-index-statistical-reports

The module automatically scrapes this page to find the latest quarterly Excel file, which contains multiple worksheets with different data breakdowns.

Update Frequency: Quarterly Geographic Coverage: Northern Ireland Reference Period: Q1 2005 - present Index Base: Q1 2023 = 100

See [here](https://andrewbolster.info/2022/03/NI-House-Price-Index.html) for more details.

Example

>>> from bolster.data_sources.ni_house_price_index import get_hpi_trends, get_sales_volumes
>>> hpi = get_hpi_trends()
>>> 'NI House Price Index' in hpi.columns
True
>>> sales = get_sales_volumes()
>>> 'Total' in sales.columns
True

Attributes

logger

DEFAULT_URL

CACHE_DIR

TABLE_TRANSFORMATION_MAP

Exceptions

NIHPIDataError

Base exception for NI HPI data errors.

NIHPIDataNotFoundError

Data file not available.

Functions

clear_cache()

Clear all cached HPI data files.

get_source_url([base_url])

Find the URL of the latest HPI Excel file from the publication page.

pull_sources([base_url, force_refresh, cache_ttl_hours])

Pull raw NI House Price Index Excel from finance-ni.gov.uk.

basic_cleanup(df[, offset])

Generic cleanup operations for NI HPI data.

cleanup_contents(df)

Fix Contents table of NI HPI Stats.

cleanup_price_by_property_type_agg(df[, offset])

NI HPI & Standardised Price Statistics by Property Type (Aggregate Table).

cleanup_price_by_property_type(df[, offset])

NI HPI & Standardised Price Statistics by Property Type (Per Class).

cleanup_with_munged_quarters_and_total_rows(df[, offset])

Number of Verified Residential Property Sales.

cleanup_with_LGDs(df[, offset])

Standardised House Price & Index for each Local Government District.

cleanup_combined_year_quarter(df[, offset])

Cleanup tables with combined 'Q1 2005' year/quarter format.

cleanup_missing_year_quarter(df[, offset])

Standardised House Price & Index for Rural Areas by drive times.

transform_sources(source_df)

Transform all raw tables using registered transformation functions.

get_all_tables([force_refresh])

Get all HPI tables as a dictionary of DataFrames.

get_hpi_trends([force_refresh])

Get NI House Price Index trends over time (Table 1).

get_sales_volumes([force_refresh])

Get property sales volumes by type (Table 4).

get_average_prices([force_refresh])

Get NI average sale prices over time (Table 9).

get_hpi_by_lgd([force_refresh])

Get HPI and prices for each Local Government District (Table 5).

get_hpi_by_property_type([force_refresh])

Get HPI summary by property type (Table 2).

build()

Pulls and cleans up the latest NI House Price Index Data.

Module Contents

bolster.data_sources.ni_house_price_index.logger[source]
bolster.data_sources.ni_house_price_index.DEFAULT_URL = 'https://www.finance-ni.gov.uk/publications/ni-house-price-index-statistical-reports'[source]
bolster.data_sources.ni_house_price_index.CACHE_DIR[source]
bolster.data_sources.ni_house_price_index.TABLE_TRANSFORMATION_MAP[source]
exception bolster.data_sources.ni_house_price_index.NIHPIDataError[source]

Bases: Exception

Base exception for NI HPI data errors.

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

exception bolster.data_sources.ni_house_price_index.NIHPIDataNotFoundError[source]

Bases: NIHPIDataError

Data file not available.

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

bolster.data_sources.ni_house_price_index.clear_cache()[source]

Clear all cached HPI data files.

bolster.data_sources.ni_house_price_index.get_source_url(base_url=DEFAULT_URL)[source]

Find the URL of the latest HPI Excel file from the publication page.

Parameters:

base_url – URL of the publication listing page

Returns:

URL of the Excel file

Raises:

NIHPIDataNotFoundError – If no Excel file found

Return type:

str

bolster.data_sources.ni_house_price_index.pull_sources(base_url=DEFAULT_URL, force_refresh=False, cache_ttl_hours=24 * 7)[source]

Pull raw NI House Price Index Excel from finance-ni.gov.uk.

Downloads the latest HPI Excel file and returns all worksheets as a dictionary of DataFrames. Files are cached locally to avoid repeated downloads.

Parameters:

  • base_url (str) – URL of the publication listing page

  • force_refresh (bool) – If True, bypass cache and download fresh data

  • cache_ttl_hours (int) – Cache validity in hours (default: 7 days)

Returns:

Dictionary mapping sheet names to raw DataFrames

Raises:

NIHPIDataNotFoundError – If source file not found or download fails

Return type:

dict[str, pandas.DataFrame]

bolster.data_sources.ni_house_price_index.basic_cleanup(df, offset=1)[source]

Generic cleanup operations for NI HPI data.

Operations performed:

  • Re-header from Offset row and translate table to eliminate incorrect headers

  • Remove any columns with ‘Nan’ or ‘None’ in the given offset-row

  • If ‘NI’ appears and all the values are 100, remove it

  • Remove any rows below and including the first ‘all nan’ row (gets most tail-notes)

  • If ‘Sale Year’,’Sale Quarter’ appear in the columns, replace with ‘Year’,’Quarter’ respectively

  • For Year; forward fill any none/nan values

  • If Year/Quarter appear, add a new composite ‘Period’ column with a PeriodIndex columns representing the year/quarter (i.e. 2022-Q1)

  • Reset and drop the index

  • Attempt to infer the new/current column object types

Parameters:

  • df (pandas.DataFrame) – DataFrame to clean

  • offset – Row offset to find headers

Returns:

Cleaned DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_contents(df)[source]

Fix Contents table of NI HPI Stats.

  • Shift/rebuild headers

  • Strip Figures because they’re gonna be broken anyway

Parameters:

df (pandas.DataFrame) – Raw DataFrame from Excel

Returns:

Cleaned DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_price_by_property_type_agg(df, offset=2)[source]

NI HPI & Standardised Price Statistics by Property Type (Aggregate Table).

Standard cleanup with a split to remove trailing index date data.

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset (int) – Row offset to find headers (default: 2)

Returns:

Cleaned DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_price_by_property_type(df, offset=2)[source]

NI HPI & Standardised Price Statistics by Property Type (Per Class).

Standard cleanup, removing the property class from the table columns.

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset (int) – Row offset to find headers (default: 2)

Returns:

Cleaned DataFrame with simplified column names

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_with_munged_quarters_and_total_rows(df, offset=3)[source]

Number of Verified Residential Property Sales.

  • Regex ‘Quarter X’ to ‘QX’ in future ‘Sales Quarter’ column

  • Drop Year Total rows

  • Clear any Newlines from the future ‘Sales Year’ column

  • Call basic_cleanup with offset=3

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset – Number of header rows to skip during cleanup

Returns:

Cleaned DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_with_LGDs(df, offset=2)[source]

Standardised House Price & Index for each Local Government District.

Builds multi-index of LGD / Metric [Index,Price] for the 11 NI LGDs.

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset (int) – Row offset to find headers (default: 2)

Returns:

Cleaned DataFrame with LGD multi-index columns

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_combined_year_quarter(df, offset=2)[source]

Cleanup tables with combined ‘Q1 2005’ year/quarter format.

Parses the combined format into Period, Year, and Quarter columns for consistency with other tables.

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset (int) – Row offset to find headers (default: 2)

Returns:

Cleaned DataFrame with Period, Year, Quarter columns

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.cleanup_missing_year_quarter(df, offset=1)[source]

Standardised House Price & Index for Rural Areas by drive times.

Inserts Year/Quarter headers and cleans normally.

Parameters:

  • df (pandas.DataFrame) – Raw DataFrame from Excel

  • offset (int) – Row offset to find headers (default: 1)

Returns:

Cleaned DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.ni_house_price_index.transform_sources(source_df)[source]

Transform all raw tables using registered transformation functions.

Parameters:

source_df (dict[str, pandas.DataFrame]) – Dictionary of raw DataFrames from Excel file

Returns:

Dictionary of cleaned/transformed DataFrames

Raises:

RuntimeError – If transformation fails for any table

Return type:

dict[str, pandas.DataFrame]

bolster.data_sources.ni_house_price_index.get_all_tables(force_refresh=False)[source]

Get all HPI tables as a dictionary of DataFrames.

This is the main entry point for accessing NI House Price Index data. Returns all available tables in a dictionary keyed by table name.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

Table 1 (NI HPI Trends), Table 2/2a-d (HPI by Property Type), Table 3/3a-c (New/Existing Dwelling), Table 4 (Sales Volumes by Property Type), Table 5/5a (HPI/Sales by LGD), Table 6-8 (Urban/Rural/Drive Times), Table 9/9a-d (Average Sale Prices), Table 10a-k (Sales Volumes by Property Type per LGD).

Return type:

Dictionary mapping table names to cleaned DataFrames. Tables include

Example

>>> tables = get_all_tables()
>>> 'Table 1' in tables
True

Get NI House Price Index trends over time (Table 1).

Returns quarterly HPI values, standardised prices, and percentage changes from Q1 2005 to present.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • Period: Quarterly period (e.g., 2005Q1)

  • Year: Year

  • Quarter: Quarter (Q1-Q4)

  • NI House Price Index: Index value (Q1 2023 = 100)

  • NI House Standardised Price: Price in GBP

  • Quarterly Change: Percentage change from previous quarter

  • Annual Change: Percentage change from same quarter previous year

Return type:

DataFrame with columns

Example

>>> hpi = get_hpi_trends()
>>> 'NI House Price Index' in hpi.columns
True
bolster.data_sources.ni_house_price_index.get_sales_volumes(force_refresh=False)[source]

Get property sales volumes by type (Table 4).

Returns quarterly counts of verified residential property sales broken down by property type.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • Period: Quarterly period

  • Year: Year

  • Quarter: Quarter

  • Detached: Detached house sales

  • Semi-Detached: Semi-detached sales

  • Terrace: Terraced house sales

  • Apartment: Apartment sales

  • Total: Total sales

Return type:

DataFrame with columns

Example

>>> sales = get_sales_volumes()
>>> 'Total' in sales.columns
True
bolster.data_sources.ni_house_price_index.get_average_prices(force_refresh=False)[source]

Get NI average sale prices over time (Table 9).

Returns simple mean, median, and standardised (HPI) prices for all property sales.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • Period: Quarterly period

  • Year: Year

  • Quarter: Quarter

  • Simple Mean: Average sale price

  • Simple Median: Median sale price

  • Standardised Price (HPI): Quality-adjusted price

Return type:

DataFrame with columns

Example

>>> prices = get_average_prices()
>>> 'Simple Median' in prices.columns
True
bolster.data_sources.ni_house_price_index.get_hpi_by_lgd(force_refresh=False)[source]

Get HPI and prices for each Local Government District (Table 5).

Returns standardised house prices and HPI for all 11 NI LGDs.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • Period, Year, Quarter: Time dimensions
    • {LGD_Name}: For each of the 11 LGDs

      • Index: HPI value

      • Price: Standardised price

LGDs include: Antrim and Newtownabbey, Ards and North Down, Armagh City Banbridge and Craigavon, Belfast, Causeway Coast and Glens, Derry City and Strabane, Fermanagh and Omagh, Lisburn and Castlereagh, Mid and East Antrim, Mid Ulster, Newry Mourne and Down

Return type:

DataFrame with multi-index columns

Example

>>> lgd = get_hpi_by_lgd()
>>> 'Period' in lgd.columns
True
bolster.data_sources.ni_house_price_index.get_hpi_by_property_type(force_refresh=False)[source]

Get HPI summary by property type (Table 2).

Returns latest quarter’s HPI and price statistics broken down by property type (Detached, Semi-Detached, Terrace, Apartment).

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • Property Type: Type of property

  • Index: HPI value

  • Percentage Change on Previous Quarter

  • Percentage Change over 12 months

  • Standardised Price

Return type:

DataFrame with columns

Example

>>> by_type = get_hpi_by_property_type()
>>> 'Property Type' in by_type.columns
True
bolster.data_sources.ni_house_price_index.build()[source]

Pulls and cleans up the latest NI House Price Index Data.

Deprecated since version Use: get_all_tables() instead for a more descriptive API.

Returns:

Dictionary of cleaned DataFrames keyed by table name.

Return type:

dict[str, pandas.DataFrame]