bolster.data_sources.nisra.homelessness

Northern Ireland Homelessness Bulletin statistics.

Biannual homelessness statistics from the Department for Communities NI (DfC), sourced from Northern Ireland Housing Executive (NIHE) casework records. Covers homeless presentations, acceptances, and temporary accommodation placements, broken down by Local Government District (LGD).

Data is published approximately every six months (Apr–Sep and Oct–Mar periods), roughly three months after each period ends.

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

Publisher:

Department for Communities NI (DfC) / Northern Ireland Housing Executive (NIHE). Publication hub: https://www.communities-ni.gov.uk/articles/northern-ireland-homelessness-bulletin

Coverage:

Biannual, 2018/19 to present. Geography: 11 Local Government Districts (LGDs) + NI total.

Example

>>> from bolster.data_sources.nisra import homelessness
>>> df = homelessness.get_latest_data(section='presentations')
>>> 'lgd' in df.columns
True

Attributes

logger

Functions

get_latest_publication_url()

Scrape the DfC hub page for the latest homelessness bulletin Excel URL.

parse_presentations(file_path)

Parse the presentations-by-LGD sheet from a homelessness bulletin workbook.

parse_acceptances(file_path)

Parse the acceptances-by-LGD sheet from a homelessness bulletin workbook.

get_latest_data([section, force_refresh])

Download and return the latest NI homelessness bulletin data.

validate_data(df[, section])

Validate a homelessness bulletin DataFrame.

Module Contents

bolster.data_sources.nisra.homelessness.logger[source]
bolster.data_sources.nisra.homelessness.get_latest_publication_url()[source]

Scrape the DfC hub page for the latest homelessness bulletin Excel URL.

Falls back to the hardcoded 2025/26 Oct–Mar edition URL if scraping fails.

Returns:

Absolute URL of the Excel tables file.

Return type:

str

Example

>>> url = get_latest_publication_url()
>>> 'communities-ni.gov.uk' in url
True
bolster.data_sources.nisra.homelessness.parse_presentations(file_path)[source]

Parse the presentations-by-LGD sheet from a homelessness bulletin workbook.

Parameters:

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

Returns:

year, period, lgd, presentations, rate_per_1000.

Return type:

Long-format DataFrame with columns

Example

>>> df = parse_presentations('/tmp/homelessness.xlsx')
>>> set(df.columns) >= {'year', 'period', 'lgd', 'presentations'}
True
bolster.data_sources.nisra.homelessness.parse_acceptances(file_path)[source]

Parse the acceptances-by-LGD sheet from a homelessness bulletin workbook.

Parameters:

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

Returns:

year, period, lgd, acceptances, rate_per_1000.

Return type:

Long-format DataFrame with columns

Example

>>> df = parse_acceptances('/tmp/homelessness.xlsx')
>>> set(df.columns) >= {'year', 'period', 'lgd', 'acceptances'}
True
bolster.data_sources.nisra.homelessness.get_latest_data(section='presentations', force_refresh=False)[source]

Download and return the latest NI homelessness bulletin data.

Parameters:

  • section (str) –

    Which section to return: - 'presentations' (default): Households presenting as homeless

    by LGD and period.

    • 'acceptances': Households accepted as homeless by LGD and period.

    • 'all': Both sections combined with a 'section' column.

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

Returns:

  • year (str): Reporting year label (e.g. '2025/26').

  • period (str): Six-month period (e.g. 'Oct-Mar', 'Apr-Sep').

  • lgd (str): Local Government District name, or 'Northern Ireland' for the NI-wide total.

  • presentations (int): Households presenting as homeless.

  • rate_per_1000 (float): Presentations per 1,000 population.

For section='acceptances', 'presentations' is replaced by 'acceptances'. For section='all', both are included with a 'section' column ('presentations' or 'acceptances').

Return type:

Long-format DataFrame. For section='presentations', columns are

Raises:

  • ValueError – If section is not one of the accepted values.

  • NISRADataNotFoundError – If the source file cannot be downloaded.

Example

>>> df = get_latest_data()
>>> 'lgd' in df.columns
True
>>> 'Northern Ireland' in df['lgd'].values
True
bolster.data_sources.nisra.homelessness.validate_data(df, section='presentations')[source]

Validate a homelessness bulletin DataFrame.

Parameters:
Returns:

True if all checks pass.

Raises:

NISRAValidationError – If any check fails.

Return type:

bool

Example

>>> df = get_latest_data('presentations')
>>> validate_data(df, 'presentations')
True