bolster.data_sources.nisra.planning_statistics

Northern Ireland Planning Activity Statistics.

Annual planning application statistics for Northern Ireland, published by the Department for Infrastructure (DfI). Provides counts of planning applications received, decided, approved and withdrawn, broken down by Local Government District or NI-wide totals.

Data is fetched from the NISRA PxStat API. Coverage begins 2015/16.

Original data source:

https://www.infrastructure-ni.gov.uk/articles/planning-activity-statistics

PxStat matrices used:

PALGD: Annual planning applications by Local Government District
PAPLGD: Annual approved planning applications by LGD and application type
PADAA: Annual planning applications by Assembly Area

Update Frequency:

Annual (financial year April-March).

Geographic Coverage:

Northern Ireland - whole-country totals plus the 11 local council areas (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).

Example

>>> from bolster.data_sources.nisra import planning_statistics
>>> df = planning_statistics.get_latest_data()
>>> 'applications_received' in df.columns
True

Attributes

logger

Functions

`parse_planning_by_lgd`([force_refresh])	Parse annual planning applications by Local Government District (PALGD).
`parse_planning_by_assembly_area`([force_refresh])	Parse annual planning applications by Assembly Area (PADAA).
`get_latest_data`([force_refresh])	Download and return NI-wide annual planning applications (all LGDs).
`get_latest_council_data`([force_refresh])	Return council-area planning applications (excludes NI aggregate).
`get_latest_planning_statistics`([dimension, ...])	Get planning application statistics for a given dimension.
`validate_data`(df)	Validate an annual planning applications DataFrame.
`get_annual_totals`(df)	Aggregate a DataFrame to annual (financial-year) totals across all areas.
`get_council_summary`(council_df[, financial_year])	Summarise council-area data by council across all (or one) financial year.

Module Contents

bolster.data_sources.nisra.planning_statistics.logger[source]

bolster.data_sources.nisra.planning_statistics.parse_planning_by_lgd(force_refresh=False)[source]

Parse annual planning applications by Local Government District (PALGD).

Parameters:: force_refresh (bool) – Accepted for API compatibility but ignored.
Returns:: financial_year, date, year, council, applications_received, applications_decided, applications_approved, applications_withdrawn, approval_rate. The NI-wide aggregate row (council=’Northern Ireland’) is included.
Return type:: DataFrame with columns

bolster.data_sources.nisra.planning_statistics.parse_planning_by_assembly_area(force_refresh=False)[source]

Parse annual planning applications by Assembly Area (PADAA).

Parameters:: force_refresh (bool) – Accepted for API compatibility but ignored.
Returns:: financial_year, date, year, assembly_area, applications_received, applications_decided, applications_approved, applications_withdrawn, approval_rate. The NI-wide aggregate row is included.
Return type:: DataFrame with columns

bolster.data_sources.nisra.planning_statistics.get_latest_data(force_refresh=False)[source]

Download and return NI-wide annual planning applications (all LGDs).

Parameters:: force_refresh (bool) – Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching.
Returns:: DataFrame from parse_planning_by_lgd() with all councils and NI-wide totals.
Return type:: pandas.DataFrame

Example

>>> df = get_latest_data()
>>> 'applications_received' in df.columns
True

bolster.data_sources.nisra.planning_statistics.get_latest_council_data(force_refresh=False)[source]

Return council-area planning applications (excludes NI aggregate).

Parameters:: force_refresh (bool) – Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching.
Returns:: DataFrame with one row per (financial_year, council), excluding the NI-wide total row.
Return type:: pandas.DataFrame

Example

>>> df = get_latest_council_data()
>>> 'council' in df.columns
True

bolster.data_sources.nisra.planning_statistics.get_latest_planning_statistics(dimension='ni', financial_year=None, summary=False, force_refresh=False)[source]

Get planning application statistics for a given dimension.

Parameters:

dimension (str) – Breakdown dimension — ‘ni’ for NI-wide total, ‘council’ for LGD breakdown, or ‘assembly’ for Assembly Area breakdown.
financial_year (str | None) – Optional financial year filter (e.g. ‘2024/25’). If None, all available years are returned.
summary (bool) – If True, return a summary aggregated across all financial years for each area.
force_refresh (bool) – Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching.

Returns:

DataFrame with planning application counts and approval rate.

Raises:

ValueError – If an unsupported dimension is given.

Return type:

pandas.DataFrame

bolster.data_sources.nisra.planning_statistics.validate_data(df)[source]

Validate an annual planning applications DataFrame.

Parameters:: df (pandas.DataFrame) – DataFrame from get_latest_data() or parse_planning_by_lgd().
Returns:: True if all checks pass.
Raises:: NISRAValidationError – If the DataFrame is empty, missing required columns, has implausible values, or has too short a time series.
Return type:: bool

Example

>>> df = get_latest_data()
>>> validate_data(df)
True

bolster.data_sources.nisra.planning_statistics.get_annual_totals(df)[source]

Aggregate a DataFrame to annual (financial-year) totals across all areas.

Parameters:: df (pandas.DataFrame) – DataFrame from get_latest_data() (may include council breakdown).
Returns:: financial_year, applications_received, applications_decided, applications_approved, applications_withdrawn, approval_rate.
Return type:: DataFrame with one row per financial year and columns

Example

>>> df = get_latest_data()
>>> annual = get_annual_totals(df)
>>> 'applications_received' in annual.columns
True

bolster.data_sources.nisra.planning_statistics.get_council_summary(council_df, financial_year=None)[source]

Summarise council-area data by council across all (or one) financial year.

Parameters:

council_df (pandas.DataFrame) – DataFrame from get_latest_council_data().
financial_year (str | None) – Optional financial year to filter to (e.g. ‘2024/25’). If None, summarises across all available years.

Returns:

DataFrame with one row per council, sorted by applications_received descending.

Return type:

pandas.DataFrame

Example

>>> council_df = get_latest_council_data()
>>> summary = get_council_summary(council_df, financial_year='2024/25')
>>> 'council' in summary.columns
True