Niwa Coastal Nz

---
name: niwa-coastal-nz
description: "Search and query NIWA (National Institute of Water and Atmospheric Research) public ArcGIS open data through a lightweight no-login CLI: org-scoped dataset search plus GeoJSON layer queries for the Coastal Sensitivity Index (erosion), beach exposure, coastal landform and hinterland classification, and other national coastal and climate layers. Use when the task involves NZ coastal hazard sensitivity, coastal classification, or NIWA open geospatial datasets. Read-only; no authentication required."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "environment"
  thecolab.source_owner: "NIWA"
  thecolab.source_type: "official"
  thecolab.auth: "none"
  thecolab.access_mode: "public-api"
  thecolab.data_class: "public"
  thecolab.writes: "false"
  thecolab.browser: "false"
  thecolab.risk: "low"
  thecolab.cache_ttl: "24h"
  thecolab.schema_version: "1"
  thecolab.skill_type: "public-api"
  thecolab.pack: "nz-public-data"
  thecolab.source_url: "https://data-niwa.opendata.arcgis.com/"
  thecolab.allowed_domains: "data-niwa.opendata.arcgis.com,www.arcgis.com,hub.arcgis.com,services.arcgis.com,services3.arcgis.com,gis.niwa.co.nz"
  thecolab.last_verified: "2026-07-26"
  thecolab.health: "healthy"
  thecolab.maintainer: "@adam91holt"
---

# NIWA Coastal NZ

## Goal

Discover and query NIWA's public ArcGIS open data — the national Coastal
Sensitivity Index, beach exposure, and coastal classification layers among
~1,400 open items — through source-native catalogue, metadata, feature-query,
and MapServer identify operations.

## Use this when

- A task needs national coastal hazard sensitivity layers (CSI erosion), beach
  exposure, coastal landform type, or hinterland characteristics as GeoJSON
- A task needs to discover what datasets NIWA publishes openly

The CSI **inundation** item is still listed in NIWA's catalogue but its backing
service was withdrawn (verified 2026-07-26) — `search` will surface it and a
query against it fails with an upstream `Service not found`. Use CSI erosion,
or `searise-nz` for site-level inundation drivers.

## Do not use this for

- Weather forecasts or marine conditions (use `metservice-nz`)
- Tide predictions (use `nz-tides-surf`)
- Sea-level rise projections per coastal site (use `searise-nz`)
- Regional council hazard layers (use `wcc-arcgis-nz` for Wellington)
- Any write, upload, or account action

## Commands

```bash
python3 skills/niwa-coastal-nz/scripts/cli.py search "coastal sensitivity" --limit 5
python3 skills/niwa-coastal-nz/scripts/cli.py item c894b53b102f4f9db55278f7572ca4f6 --json
python3 skills/niwa-coastal-nz/scripts/cli.py layers c894b53b102f4f9db55278f7572ca4f6
python3 skills/niwa-coastal-nz/scripts/cli.py describe c894b53b102f4f9db55278f7572ca4f6 --layer-id 0 --json
python3 skills/niwa-coastal-nz/scripts/cli.py query c894b53b102f4f9db55278f7572ca4f6 --bbox "174.5,-41.5,175.2,-40.9" --limit 20 --json
python3 skills/niwa-coastal-nz/scripts/cli.py query c894b53b102f4f9db55278f7572ca4f6 --count --json
python3 skills/niwa-coastal-nz/scripts/cli.py identify 2e2f8ea5ea31453e808b36b2a1ca43a0 --point "174.78,-41.29" --no-geometry --json
```

- `search KEYWORD [--type TYPE] [--limit N] [--start N] [--json]` — org-scoped catalogue search, newest first; JSON preserves ArcGIS `start` and `next_start`
- `item ITEM_ID [--json]` — normalized title, type, owner, organisation, access, licence, description, tags, timestamps, size, raw item URL, and a verified service URL only for Feature/Map Services
- `layers ITEM_OR_URL [--json]` — layers/tables of a verified NIWA Feature/Map service
- `describe SERVICE [--layer-id N] [--json]` — normalized service/layer fields, aliases, types, descriptions/units when supplied, extent, spatial reference, capabilities, geometry type, object ID field, and record limit
- `query LAYER [--layer-id N] [--where SQL] [--bbox minLon,minLat,maxLon,maxLat] [--fields F1,F2] [--limit N] [--count | --ids-only] [--no-geometry] [--offset N] [--order-by FIELDS] [--geometry-precision N] [--max-allowable-offset N] [--json]` — GeoJSON by default, or normalized count/ID envelopes
- `identify SERVICE --point LON,LAT [--layer-id N] [--tolerance N] [--no-geometry] [--json]` — raw MapServer identify results using a WGS84 point

`--count` and `--ids-only` are mutually exclusive. Query offset, ordering,
geometry precision, allowable offset, and geometry suppression map directly to
the ArcGIS REST controls; they do not add scientific interpretation.

## Notes

- Licence: CC BY 4.0 — attribute NIWA (item pages carry the canonical statement)
- Searches are scoped to NIWA's ArcGIS organisation (`fp1tibNcN9mbExhG`);
  hub-wide search APIs return a global catalogue and are deliberately not used
- Layer queries require HTTPS and either a NIWA-owned host
  (`gis.niwa.co.nz`) or an Esri service path under the NIWA tenant; anything
  else is refused (exit 7). Service paths and final redirects are revalidated.
- `--point` is always `LON,LAT` and `--bbox` is always
  `minLon,minLat,maxLon,maxLat`, in WGS84. Coordinates must be finite and in
  longitude/latitude range. For Wellington, both
  `--point "174.78,-41.29"` and `--point=174.78,-41.29` forms work.
- `identify` is a raw MapServer identify primitive, not a hazard assessment.
  Its tolerance is in display pixels and results retain upstream layer,
  attribute, and geometry values.
- Useful verified items: CSI erosion `c894b53b102f4f9db55278f7572ca4f6`;
  the COAST folder on `gis.niwa.co.nz/server/rest/services` carries the
  coastal classification MapServers
- `truncated: true` means the server transfer limit was hit — narrow with
  `--where`/`--bbox`, or page with `--offset`
- Errors distinguish invalid input, blocked host/organisation, upstream
  failure, malformed response, and legitimate empty results as JSON on stderr.

## Resources

- CLI entrypoint: `scripts/cli.py`
- Contract test: `scripts/test_contract.py`; smoke test: `scripts/smoke_test.py`
- Org id discovery, host survey, and licence notes: `references/source-notes.md`