household-hardship-nz

name: household-hardship-nz description: Query New Zealand household material hardship, child and family poverty, income adequacy, housing affordability and rent burden, low-income household counts, and the Gini coefficient of income inequality from the Stats NZ Household Economic Survey "Household Wellbeing" release on data.govt.nz. Use for questions about NZ deprivation, cost-of-living stress, who is struggling to afford housing, hardship by region or ethnicity (including Maori households), or income inequality figures with confidence intervals.

Household Hardship NZ

Overview

Read-only CLI over the Stats NZ Household Economic Survey (HES) "Household Wellbeing" release, distributed on data.govt.nz through the public CKAN API. No login, API key, or browser needed. Each dataset ships as a ZIP-of-CSV that the CLI unpacks with the Python standard library only.

It answers questions like material hardship counts, income adequacy, housing affordability (housing cost as a share of income), low-income household numbers, and income inequality (Gini) — broken down by region or by ethnicity (including Maori households), each with 95% confidence intervals (LCI/UCI) and relative standard error.

When to Use

• "How many households are in material hardship in Auckland?"
• "Compare housing affordability stress across ethnicities."
• "Which regions have the worst income adequacy?"
• "Show the Gini coefficient of income inequality by region."
• "How many low-income households spend over 40% of income on housing?"
• Any NZ deprivation / cost-of-living / housing-cost-burden / inequality lookup.

Not for: live benefit caseloads, the public housing register, or building-level deprivation indexes — those live in other sources.

Commands

All commands are run via scripts/cli.py and accept --json for machine output. Most accept --dataset <ckan-id> to target a different HES release (default is the 2020-2021 wellbeing release).

--ethnicity and --tenure take an optional value: bare --ethnicity returns all groups; --ethnicity European filters to one. Without --ethnicity or --tenure, breakdowns are by region (optionally filtered with --region auckland). --threshold accepts 30, 40, or 50.

Examples

# Material hardship households in Auckland with confidence intervals
python3 scripts/cli.py hardship --region auckland

# Material hardship by ethnicity, as JSON
python3 scripts/cli.py hardship --ethnicity --json

# Low-income households spending over 30% of income on housing, by ethnicity
python3 scripts/cli.py affordability --ethnicity --threshold 30 --lowincome --json

# Income adequacy across all regions
python3 scripts/cli.py income-adequacy

# Gini coefficient of income inequality by region
python3 scripts/cli.py gini

# Find other HES wellbeing releases (e.g. 2018-19, "Warm and Dry")
python3 scripts/cli.py search "warm and dry"
python3 scripts/cli.py datasets

Notes

• Source: Stats NZ HES Household Wellbeing, via the data.govt.nz CKAN API. The default dataset is household-economic-survey-2020-2021-household-wellbeing-including-maori-households.
• All counts are survey estimates with sampling error: lci/uci are the 95% confidence bounds and rse_percent the relative standard error. A flag of * marks estimates Stats NZ flags as having high sampling error.
• Region and ethnicity names are matched loosely (case/punctuation-insensitive), so auckland, hawkes bay, and Maori all work.
• Endpoint detail, table names, and column meanings are in references/api-notes.md.
• Run python3 scripts/smoke_test.py to verify the live data path.