bolster.data_sources.nisra.housing_stock

Northern Ireland Housing Stock Statistics.

Annual housing stock statistics for Northern Ireland, published by Land and Property Services (LPS), a division of the Department of Finance (DoF) NI. Provides dwelling counts by property type (converted apartment, purpose built apartment, detached, semi-detached, terrace) at LGD, Electoral Ward, and Super Output Area level.

Note: This data is not available in the NISRA PxStat API. It is published directly by DoF/LPS as Excel workbooks.

Publisher:

Department of Finance NI (DoF) — Land and Property Services (LPS). This data is NOT published by NISRA directly; the source is: https://www.finance-ni.gov.uk/topics/housing-stock-statistics

Data files (confirmed 2026 edition):
Coverage:

Annual (April/May reference date), 2008–2026. Geography: 11 Local Government Districts (LGDs) + NI total.

Example

>>> from bolster.data_sources.nisra import housing_stock
>>> df = housing_stock.get_latest_housing_stock(geo='lgd')
>>> 'total' in df.columns
True

Attributes

logger

Functions

get_latest_publication_url([geo])

Scrape the DoF NI housing stock page for the latest Excel download URL.

parse_lgd_file(file_path)

Parse the LGD-level housing stock Excel workbook into a tidy DataFrame.

get_latest_housing_stock([geo, force_refresh])

Download and return NI housing stock data in long format.

validate_housing_stock(df)

Validate an LGD housing stock DataFrame.

Module Contents

bolster.data_sources.nisra.housing_stock.logger[source]
bolster.data_sources.nisra.housing_stock.get_latest_publication_url(geo='lgd')[source]

Scrape the DoF NI housing stock page for the latest Excel download URL.

Attempts to find the most recent Excel link on the source page. Falls back to the hardcoded 2026 URL if scraping fails or returns no match.

Parameters:

geo (str) – Geography type — ‘lgd’ (default), ‘ward’, or ‘soa’.

Returns:

Absolute URL of the Excel file.

Return type:

str

Example

>>> url = get_latest_publication_url('lgd')
>>> url.endswith('.xlsx')
True
bolster.data_sources.nisra.housing_stock.parse_lgd_file(file_path)[source]

Parse the LGD-level housing stock Excel workbook into a tidy DataFrame.

Iterates over every data sheet (Table 1.1 … Table 1.19), extracts the reference year from the sheet title, parses the 11-LGD table plus the NI aggregate row, and stacks all years into a single long-format DataFrame.

Parameters:

file_path (str | object) – Path to the downloaded Excel file.

Returns:

year, lgd_code, lgd_name, converted_apartment, purpose_built_apartment, detached, semi_detached, terrace, total.

Return type:

Long-format DataFrame with columns

Example

>>> import pathlib
>>> df = parse_lgd_file("/tmp/housing_stock_lgd.xlsx")
>>> 'total' in df.columns
True
bolster.data_sources.nisra.housing_stock.get_latest_housing_stock(geo='lgd', force_refresh=False)[source]

Download and return NI housing stock data in long format.

Parameters:

  • geo (str) – Geography granularity: - 'lgd' (default): 11 Local Government Districts + NI total. - 'ward': Electoral Ward level. - 'soa': Super Output Area level.

  • force_refresh (bool) – If True, bypass the local file cache and re-download the source file.

Returns:

  • year (int): Reference year (e.g. 2008).

  • lgd_code (str): LGD 2014 code (e.g. "N09000001").

  • lgd_name (str): LGD name (e.g. "Antrim and Newtownabbey"), or "Northern Ireland" for the NI-wide total row.

  • converted_apartment (int): Converted apartment dwellings.

  • purpose_built_apartment (int): Purpose-built apartment dwellings.

  • detached (int): Detached dwellings.

  • semi_detached (int): Semi-detached dwellings.

  • terrace (int): Terrace dwellings.

  • total (int): Total housing stock.

Ward and SOA files share the same column schema but may have additional geography columns.

Return type:

Long-format DataFrame. For geo='lgd' the columns are

Raises:

  • ValueError – If geo is not one of 'lgd', 'ward', 'soa'.

  • NISRADataNotFoundError – If the source file cannot be downloaded.

Example

>>> df = get_latest_housing_stock(geo='lgd')
>>> set(df.columns) >= {'year', 'lgd_code', 'lgd_name', 'total'}
True
bolster.data_sources.nisra.housing_stock.validate_housing_stock(df)[source]

Validate an LGD housing stock DataFrame.

Checks that the DataFrame has the expected structure and plausible values.

Parameters:

df (pandas.DataFrame) – DataFrame returned by get_latest_housing_stock().

Returns:

True if all checks pass.

Raises:

NISRAValidationError – If any check fails, with a descriptive message.

Return type:

bool

Example

>>> df = get_latest_housing_stock()
>>> validate_housing_stock(df)
True