NZ OGC Records

Search NZ catalogue metadata with the stdlib Python CLI in scripts/cli.py. Use this to find datasets and distribution URLs before querying the data service.

Commands

python3 skills/nz-ogc-records/scripts/cli.py catalogues --json
python3 skills/nz-ogc-records/scripts/cli.py search flood --catalogue auckland-council --limit 5 --json
python3 skills/nz-ogc-records/scripts/cli.py search traffic --catalogue waka-kotahi --bbox 174.4,-37.2,175.3,-36.4 --limit 5 --format geojson
python3 skills/nz-ogc-records/scripts/cli.py get auckland-transport eeb0839fbd594c9e87189df5c84c2543 --json

• catalogues probes all five endpoints and reports availability and upstream matched counts. Failed probes remain status rows; all failed probes exit non-zero.
• search TEXT searches all catalogues by default. Repeat --catalogue to select several. Names: auckland-council, auckland-transport, waka-kotahi, niwa, data-govt-nz. --limit is per catalogue, from 1 to 100. The CLI returns one bounded page per catalogue and exposes next_urls without following them. Upstream matching/ranking may include related terms.
• get CATALOGUE RECORD_ID accepts the record's id from search. Hub can resolve an item ID to a layer ID with a suffix such as _0; retain the returned ID.
• --bbox minLon,minLat,maxLon,maxLat filters catalogue coverage in WGS84. Use increasing bounds; split antimeridian searches into two boxes. Extents can be broad or absent and do not establish local data coverage. Filtering occurs upstream and uses coverage intersection on Hub and CKAN (ext_bbox), rather than containment. National-coverage records can intersect tiny boxes.
• Search and get accept --format geojson; geometries describe metadata coverage, not dataset features. Records without geometry have null geometry.

Workflow and interpretation

1. Check catalogues when selecting a source. CKAN search/get and the four OGC catalogues were verified live on 8 October 2026 from an NZ network. Some overseas networks receive an Incapsula bot challenge, reported as blocked (exit 4); nzfetch proxy fallback applies. CKAN fixtures are marked synthetic.
2. Search relevant catalogues, inspect catalogues, partial, and warnings, and use returned IDs with get to review the record.
3. Check each record's licence, licence_info, attribution, description and dates. NIWA includes non-commercial licences. updated_at is a catalogue modification date; latest_data is omitted unless the source explicitly provides it. Do not label old survey data current because metadata changed.
4. Hand FeatureServer/MapServer URLs in distribution_urls to nz-arcgis when available. ImageServer URLs require a raster-capable client. File downloads can be large; review their format before downloading.

JSON success output is exactly {"meta": {...}, "results": [...]}; get also returns an array. meta carries source_url, publisher, and retrieved_at (UTC), plus catalogue statuses, query settings, partial and warnings. Mixed-source records and distributions carry their own provenance. licence and latest_data are omitted when unknown. custom/none Hub licence markers use a plain-text excerpt of licence terms, cut at a word boundary within 300 characters with an ellipsis when truncated; inspect licence_info for the full terms. GeoJSON uses meta as a foreign member. Failures use meta, results: [], and error with numeric code, contract type and message; rate limits preserve retry_after. No keys or sign-in are used. Linked distributions are surfaced, not fetched or checked for their own availability or authentication requirements. Search may succeed with partial results; all unavailable catalogues produce a non-zero search or catalogues exit. Empty results from available sources are valid. --format json implies JSON. Blank CKAN coverage and dates are treated as absent. Malformed CKAN coverage on search retains the record with geometry: null, geometry_warning and a metadata warning; fetching that record with get reports schema failure.

Read references/source-notes.md for endpoint, fixture and parser details. Run scripts/test_contract.py for deterministic checks and scripts/smoke_test.py for bounded live verification.