bolster.data_sources.nisra.planning_statistics ============================================== .. py:module:: bolster.data_sources.nisra.planning_statistics .. autoapi-nested-parse:: 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). .. rubric:: Example >>> from bolster.data_sources.nisra import planning_statistics >>> df = planning_statistics.get_latest_data() >>> 'applications_received' in df.columns True Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.planning_statistics.logger Functions --------- .. autoapisummary:: bolster.data_sources.nisra.planning_statistics.parse_planning_by_lgd bolster.data_sources.nisra.planning_statistics.parse_planning_by_assembly_area bolster.data_sources.nisra.planning_statistics.get_latest_data bolster.data_sources.nisra.planning_statistics.get_latest_council_data bolster.data_sources.nisra.planning_statistics.get_latest_planning_statistics bolster.data_sources.nisra.planning_statistics.validate_data bolster.data_sources.nisra.planning_statistics.get_annual_totals bolster.data_sources.nisra.planning_statistics.get_council_summary Module Contents --------------- .. py:data:: logger .. py:function:: parse_planning_by_lgd(force_refresh = False) Parse annual planning applications by Local Government District (PALGD). :param force_refresh: 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. :rtype: DataFrame with columns .. py:function:: parse_planning_by_assembly_area(force_refresh = False) Parse annual planning applications by Assembly Area (PADAA). :param force_refresh: 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. :rtype: DataFrame with columns .. py:function:: get_latest_data(force_refresh = False) Download and return NI-wide annual planning applications (all LGDs). :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: DataFrame from :func:`parse_planning_by_lgd` with all councils and NI-wide totals. .. rubric:: Example >>> df = get_latest_data() >>> 'applications_received' in df.columns True .. py:function:: get_latest_council_data(force_refresh = False) Return council-area planning applications (excludes NI aggregate). :param force_refresh: 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. .. rubric:: Example >>> df = get_latest_council_data() >>> 'council' in df.columns True .. py:function:: get_latest_planning_statistics(dimension = 'ni', financial_year = None, summary = False, force_refresh = False) Get planning application statistics for a given dimension. :param dimension: Breakdown dimension — 'ni' for NI-wide total, 'council' for LGD breakdown, or 'assembly' for Assembly Area breakdown. :param financial_year: Optional financial year filter (e.g. '2024/25'). If None, all available years are returned. :param summary: If True, return a summary aggregated across all financial years for each area. :param force_refresh: 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. .. py:function:: validate_data(df) Validate an annual planning applications DataFrame. :param df: DataFrame from :func:`get_latest_data` or :func:`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. .. rubric:: Example >>> df = get_latest_data() >>> validate_data(df) True .. py:function:: get_annual_totals(df) Aggregate a DataFrame to annual (financial-year) totals across all areas. :param df: DataFrame from :func:`get_latest_data` (may include council breakdown). :returns: financial_year, applications_received, applications_decided, applications_approved, applications_withdrawn, approval_rate. :rtype: DataFrame with one row per financial year and columns .. rubric:: Example >>> df = get_latest_data() >>> annual = get_annual_totals(df) >>> 'applications_received' in annual.columns True .. py:function:: get_council_summary(council_df, financial_year = None) Summarise council-area data by council across all (or one) financial year. :param council_df: DataFrame from :func:`get_latest_council_data`. :param financial_year: 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. .. rubric:: Example >>> council_df = get_latest_council_data() >>> summary = get_council_summary(council_df, financial_year='2024/25') >>> 'council' in summary.columns True