msd-benefits-nz

MSD Benefits NZ

Overview

Query official Ministry of Social Development (MSD) quarterly benefit statistics through a small deterministic CLI with human-readable and JSON output, without browser automation, login, API keys, or local cache state.

This skill wires three public MSD CSV releases:

• National main-benefit recipient counts (Jobseeker Support, Sole Parent Support, Supported Living Payment, Youth Payment and Young Parent Payment, Other Main Benefits)
• NZ Superannuation and Veteran's Pension recipient counts
• Work and Income region-level main-benefit counts

Each supports breakdowns by gender, ethnicity, age group, and (region CSV) MSD service region, plus a multi-quarter trend.

Important: these CSVs are the December 2019 "benefit fact sheets" release - a frozen historical series. The latest quarter present is Dec_19 (quarters run Dec_14 through Dec_19). Treat output as a stable historical reference set, not a live current-quarter feed. See references/api-notes.md.

When to Use

• A user asks for New Zealand benefit numbers, main benefit recipient counts, or welfare statistics
• A user wants Jobseeker, Sole Parent, Supported Living, Youth Payment, NZ Super, or Veteran's Pension recipient figures
• A user needs benefit recipients broken down by gender, ethnicity, age group, or Work and Income region
• A user wants a quarterly trend for a benefit group across 2014-2019
• Another tool or agent needs JSON output from official MSD benefit data

Do not use this for

• Current-quarter or post-2019 benefit numbers (this release stops at Dec_19; point users to msd.govt.nz benefit fact sheets for newer data)
• Individual or identifiable case data (the source is aggregated and confidentialised)
• Child poverty / material hardship / public housing register figures (those are separate Stats NZ and HUD datasets, not in this release)
• Redistributing the extract as a standalone dataset

Commands

Run with:

python3 skills/msd-benefits-nz/scripts/cli.py <command> [flags]

• list-quarters [--csv national|nzs|region] [--json] - distinct Quarter values available in a CSV
• main-benefits [--quarter Sep_19] [--group 'Jobseeker Support'] [--gender] [--ethnicity] [--age] [--json] - national main-benefit counts; default groups by benefit when no breakdown flag is given
• nz-super [--quarter Sep_19] [--group ...] [--age-group] [--ethnicity] [--json] - NZ Super / Veteran's Pension counts (age is Under 65 / 65 and over)
• region --region 'Auckland Metro' [--quarter Sep_19] [--group ...] [--gender] [--ethnicity] [--age] [--json] - Work and Income region breakdown
• trend --group 'Sole Parent Support' [--gender F] [--json] - time series of recipient Count across all quarters

Quarter format is Mon_YY, e.g. Mar_15, Dec_19. Default quarter is Dec_19 (the latest in the release). Region values are MSD Work and Income service regions (e.g. Auckland Metro, Wellington, Canterbury), not regional councils.

Examples

python3 skills/msd-benefits-nz/scripts/cli.py list-quarters --csv national --json
python3 skills/msd-benefits-nz/scripts/cli.py main-benefits --quarter Sep_19 --json
python3 skills/msd-benefits-nz/scripts/cli.py main-benefits --quarter Sep_19 --group 'Jobseeker Support' --ethnicity --json
python3 skills/msd-benefits-nz/scripts/cli.py nz-super --quarter Sep_19 --age-group --json
python3 skills/msd-benefits-nz/scripts/cli.py region --region 'Auckland Metro' --quarter Sep_19 --group 'Sole Parent Support' --json
python3 skills/msd-benefits-nz/scripts/cli.py trend --group 'Sole Parent Support' --gender F --json

Resources

• CLI entrypoint: scripts/cli.py
• Endpoint and schema detail: references/api-notes.md

Notes

• MSD is the upstream source for all commands; cite it and include the release URL when reporting figures
• No API key, username, password, cookie, or browser session is required
• The CSVs contain Gender suppressed, Ethnicity suppressed, Age suppressed, and Unspecified categories where MSD applied confidentiality; these are summed into totals and shown as their own breakdown rows
• Default output is human-readable; every command supports --json for chaining into other tools
• --group matching is case-insensitive and accepts unique substrings; an ambiguous or unknown value lists the valid groups