deprivation-nz
Look up New Zealand small-area socioeconomic deprivation (NZDep2023) by SA1/SA2 code, place name, decile, or SA3 region - the standard index of relative poverty, material hardship, and disadvantage us
SKILL.mdskills/deprivation-nz/SKILL.md
GitHubDeprivation NZ (NZDep2023)
Goal
Query the New Zealand Index of Deprivation 2023 (NZDep2023) through a small deterministic CLI with human-readable and JSON output, without browser automation, login, API keys, or local cache state.
NZDep2023 ranks every small area in New Zealand on relative socioeconomic deprivation. Decile 1 = least deprived, decile 10 = most deprived. It is the standard proxy for area-level poverty, material hardship, and disadvantage used across health, housing, education, and social-policy analysis.
This skill ships support for:
- Per-area deprivation decile, raw score, and population for Statistical Area 1 (SA1)
- Averaged deprivation decile/score for Statistical Area 2 (SA2), with parent SA3 region
- Name search over SA2 area names (returns SA1 or SA2 detail)
- Listing areas in a specific deprivation decile
- Listing all SA2 areas inside an SA3 region with their deprivation
- A national summary of the SA1 decile distribution
Use this when
- A user asks how deprived, poor, or disadvantaged a New Zealand suburb, street, or area is
- A user needs the NZDep2023 decile or score for an SA1 or SA2 code, or for a named place
- A workflow needs area-level deprivation as a proxy for child poverty, material hardship, or need
- A user is matching deprivation to health, housing, school decile, or funding allocation
- Another tool or agent needs machine-readable NZDep2023 values
Do not use this for
- Individual or household income, benefit numbers, or the public housing register (NZDep is area-level only, not person-level)
- Geospatial boundary polygons, maps, or GIS overlays (this CLI requests
returnGeometry=false) - Older indexes (NZDep2018, NZDep2013) - only the 2023 release is wired
- Census microdata or confidentialised unit records
- Redistributing the dataset as a standalone product
CLI
Run with:
python3 skills/deprivation-nz/scripts/cli.py <command> [flags]
Every command supports --json for machine-readable output; the default is human-readable.
Commands
sa1 --code <SA1_code> [--json]- NZDep2023 decile, score, and population for a 7-digit SA1 areasa2 --code <SA2_code> [--json]- averaged NZDep2023 decile/score for a 6-digit SA2 area, plus its SA3 regionsearch --name <text> [--level sa1|sa2] [--limit N] [--json]- find areas whose SA2 name matches textdecile --value <1-10> [--level sa1|sa2] [--limit N] [--json]- list areas in a given deprivation decileregion --sa3 <SA3_name> [--limit N] [--json]- list SA2 areas within an SA3 region with their deprivationstats [--json]- national count and decile distribution across all SA1 areas
Examples:
python3 skills/deprivation-nz/scripts/cli.py sa1 --code 7000000 --json
python3 skills/deprivation-nz/scripts/cli.py sa2 --code 127100
python3 skills/deprivation-nz/scripts/cli.py search --name "Auckland" --level sa2 --limit 10 --json
python3 skills/deprivation-nz/scripts/cli.py decile --value 10 --level sa2 --limit 20 --json
python3 skills/deprivation-nz/scripts/cli.py region --sa3 "Northcote (Auckland)" --json
python3 skills/deprivation-nz/scripts/cli.py stats --json
Resources
- CLI entrypoint:
scripts/cli.py - Feature service and field notes:
references/api-notes.md
Notes
- Source: New Zealand Index of Deprivation 2023 (NZDep2023), University of Auckland / Stats NZ, published as a public ArcGIS Feature Service (no login, no key)
- Decile 1 is least deprived; decile 10 is most deprived - always state the direction when reporting
- SA1 carries the per-area decile/score/population; SA2 carries area-averaged values plus the parent SA3 region
searchandregionmatch on names case-insensitively using an ArcGISLIKEquery; name input is validated to safe characters before being sent- The service caps each query at 2,000 records; use
--limitand narrower filters for large regions - Cite NZDep2023 as the upstream source when reporting figures, and note that it measures area-level relative deprivation, not individual circumstances
- Default output is human-readable; every command supports
--jsonfor chaining into other tools