safeswim-nz

SafeSwim NZ

Goal

Query live SafeSwim NZ swimming-location water-quality and swimming-condition data with a deterministic CLI and JSON output.

Use this when

• A user asks whether it's safe to swim at a SafeSwim-supported NZ beach, lake, or swimming spot today
• A user wants water quality status (GREEN/AMBER/RED/RED+/BLACK) for SafeSwim locations
• A user asks about wastewater overflow alerts or swimming hazards
• A user wants hour-by-hour swimming forecasts (water temp, wind, UV, tide height)
• A user needs nearby SafeSwim locations, optionally filtered by warning severity
• A workflow needs machine-readable swimming-location safety data

Do not use this for

• General freshwater monitoring outside SafeSwim coverage; use lawa-nz for broader river/lake sites
• Tide predictions alone; use nz-tides-surf for LINZ tide tables
• Surf conditions; use nz-tides-surf for SwellMap surf data
• Swimming spots outside the SafeSwim API coverage area
• Historical water-quality records beyond what the live API returns
• Safety-critical decisions without also checking local signage and conditions

Preferred workflow

1. Run scripts/cli.py list to discover SafeSwim locations, optionally filtered by search text
2. Use detail <slug> for a specific location with hour-by-hour forecast data
3. Use nearby <lat> <lon> to find SafeSwim locations close to a coordinate
4. Use --min-risk RED when the user wants warning-level or worse locations, not safe-swim recommendations
5. Use --json for agent chaining, alerts, or structured reports
6. Mention that SafeSwim data is live and can change rapidly after rainfall events

CLI

Run with:

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

Commands

• list [--search TEXT] [--limit N] [--json] — list SafeSwim locations with quality status and patrol info
• detail <slug> [--json] — full detail for a location: forecasts, tags, alerts, facilities
• nearby <lat> <lon> [--radius N] [--min-risk GREEN|AMBER|RED|RED+|BLACK] [--limit N] [--json] — SafeSwim locations near a coordinate ordered by distance; --min-quality is accepted as a compatibility alias

Examples:

python3 skills/safeswim-nz/scripts/cli.py list --search takapuna --limit 5
python3 skills/safeswim-nz/scripts/cli.py detail takapuna --json
python3 skills/safeswim-nz/scripts/cli.py nearby -36.8485 174.7633 --radius 10 --min-risk RED

Resources

• CLI entrypoint: scripts/cli.py
• Smoke test: scripts/smoke_test.py
• API notes: references/api-notes.md

Notes

• No API key, username, password, cookie, or browser automation is required
• The SafeSwim API is public and read-only at safeswim.org.nz/api
• Water quality can change rapidly after rainfall — treat results as current snapshots
• GREEN = lower risk, AMBER = caution, RED/RED+ = unsafe, BLACK = wastewater overflow
• Not all locations provide the full forecast array; some data arrays may be sparse
• SafeSwim covers only locations returned by the live API; it is not an all-NZ waterway catalogue
• The CLI fetches the full location list once and filters in-process; repeated hits within a second reuse the cached fetch