bolster.data_sources.nisra.claimant_count

NISRA Claimant Count Statistics Module.

Provides monthly Claimant Count statistics for Northern Ireland via the NISRA PxStat API. The Claimant Count is an experimental statistic measuring the number of people claiming benefits principally for the reason of being unemployed. Data is published monthly and covers Northern Ireland with two geographic breakdowns: Local Government Districts and Assembly Areas.

Original data source:

https://www.nisra.gov.uk/statistics/labour-market-and-social-welfare/claimant-count

PxStat matrices used:

  • CCMLGD — monthly count and rate by LGD (11 districts + NI total)

  • CCMAA — monthly count and rate by Assembly Area (18 areas + NI total)

  • CCMSOA — monthly count by Super Output Area (~92 k rows, large)

Update Frequency: Monthly, approximately 2–3 weeks after the reference month.

Usage:
>>> from bolster.data_sources.nisra import claimant_count
>>> df = claimant_count.get_latest_claimant_count("lgd")
>>> "claimants_total" in df.columns
True

Example

>>> from bolster.data_sources.nisra import claimant_count
>>> df = claimant_count.get_latest_claimant_count("lgd")
>>> df[df["geography"] == "Northern Ireland"]["claimants_total"].iloc[0] > 0
True

Attributes

logger

Functions

get_latest_claimant_count([breakdown, adjusted, ...])

Download and return the latest NISRA claimant count data.

validate_claimant_count(df, breakdown)

Validate the integrity of a claimant count DataFrame.

Module Contents

bolster.data_sources.nisra.claimant_count.logger[source]
bolster.data_sources.nisra.claimant_count.get_latest_claimant_count(breakdown='lgd', adjusted=True, force_refresh=False)[source]

Download and return the latest NISRA claimant count data.

Fetches data from the NISRA PxStat API for the chosen geographic breakdown. Returns the full time series available from the API (from January 2005).

Note

adjusted is accepted for API compatibility but is ignored — the PxStat API does not distinguish seasonally adjusted from unadjusted counts at geographic level.

force_refresh is accepted for API compatibility but is ignored — the PxStat API is called directly with no local cache layer.

Parameters:

  • breakdown (str) –

    Geographic breakdown to return. One of:

    • "lgd" — 11 Local Government Districts + NI total (default)

    • "aa" — 18 Assembly Areas + NI total

    • "soa" — Super Output Areas (~92 k rows, large)

  • adjusted (bool) – Ignored. Retained for API compatibility.

  • force_refresh (bool) – Ignored. Retained for API compatibility.

Returns:

DataFrame with columns:

  • date: pandas Timestamp (monthly, day=1)

  • geography_code: geography identifier code

  • geography: geography name label

  • claimants_total: claimant count (float)

  • claimant_rate_total_pct: claimant rate as percentage (float)

For "soa": DataFrame with columns:

  • date: pandas Timestamp (monthly, day=1)

  • soa_code: Super Output Area code

  • soa_name: Super Output Area name

  • claimants: claimant count (float)

Return type:

For "lgd" and "aa"

Raises:

ValueError – If breakdown is not a supported value.

Example

>>> df = get_latest_claimant_count("lgd")
>>> "claimants_total" in df.columns
True
>>> df_aa = get_latest_claimant_count("aa")
>>> "claimants_total" in df_aa.columns
True
bolster.data_sources.nisra.claimant_count.validate_claimant_count(df, breakdown)[source]

Validate the integrity of a claimant count DataFrame.

Checks that required columns are present, values are in plausible ranges, and the DataFrame is non-empty.

Parameters:
Returns:

True if validation passes, False otherwise.

Return type:

bool

Example

>>> import pandas as pd
>>> validate_claimant_count(pd.DataFrame(), "lgd")
False