nz-tides-surf · git:20261011.02b5609 · 2026-10-11 · sha256 a7d1dced8abba519
nz-tides-surf git:20261011.02b5609A
Immutable. This exact content never changes and is served at /api/v1/blob/a7d1dced8abba519.
--- name: nz-tides-surf description: "Query New Zealand LINZ tide predictions, LINZ standard-port tidal levels, and SwellMap surf forecasts through a lightweight read-only CLI. Use when the task involves NZ tide times, next high/low tide, standard-port levels such as MHWS, MSL, HAT or LAT, surf forecasts, swell trend, or choosing the best nearby surf break for a drive." license: MIT compatibility: "Requires Python 3.10+ and network access for live data" metadata: thecolab.category: "environment" thecolab.source_owner: "Toitū Te Whenua LINZ and SwellMap" thecolab.source_type: "mixed" 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://www.linz.govt.nz" thecolab.allowed_domains: "developer.metservice.com,niwa.co.nz,static.charts.linz.govt.nz,www.linz.govt.nz,www.surfline.com,www.swellmap.com" thecolab.last_verified: "2026-10-12" thecolab.health: "healthy" thecolab.maintainer: "@adam91holt" --- # NZ Tides + Surf ## Goal Query live New Zealand tide and surf forecast data through a small deterministic CLI with human-readable and JSON output, without login, browser automation, account cookies, or API keys. The main workflow is answering "is Piha worth a drive tomorrow morning?" by combining official LINZ tide predictions with SwellMap surf ratings, wave height, swell period, swell direction, and wind. ## Use this when - A user asks for tide times at a New Zealand port or surf beach - A user asks for the next high tide or low tide - A user asks for a surf forecast at a known NZ break - A user wants to compare breaks in Auckland, Coromandel, Gisborne, or Wellington - A workflow needs machine-readable tide/surf rows for trip planning ## Do not use this for - Safety-critical boating, swimming, or surf rescue decisions without checking the source sites directly - Maritime warnings, official weather watches, or severe weather alerts - Authenticated Surfline features, subscriptions, cameras, or personalised forecasts - MetOcean/MetService point marine API data when an API key is available; use `metservice-nz` for that - Historical tide or surf analysis beyond the published forecast/table windows - Observed sea-level gauge archives, sensor files, or historical gauge ZIPs; use `linz-tide-gauges-nz` - Treating `levels` as a daily tide prediction or as a measured gauge height. `levels` publishes reference heights in metres on Chart Datum. `tides` remains the prediction timetable. Chart Datum is the zero of those predictions. ## Preferred workflow 1. Run `scripts/cli.py` with the narrowest subcommand that answers the task 2. Use `tides` or `next-tide` for official LINZ tide predictions 3. Use `levels` for published standard-port reference heights (MHWS, MHWN, MLWN, MLWS, ranges, MSL, HAT, LAT) in metres on Chart Datum 4. Use `surf` for a specific break forecast 5. Use `best-break` when the user asks where to drive tomorrow morning 6. Use `breaks` to see the curated surf breaks and their companion LINZ tide ports 7. Use `--json` for agent chaining, comparisons, and reports 8. Mention that surf ratings are SwellMap forecast snapshots, `tides` rows are official LINZ predictions, and `levels` rows are published reference heights rather than gauge observations ## CLI Run with: ```bash python3 skills/nz-tides-surf/scripts/cli.py <command> [flags] ``` ## Commands - `ports [--json]` - list available LINZ tide ports and common surf aliases - `levels [port] [--json]` - published LINZ standard-port tidal levels in metres on Chart Datum; omit the port to return the whole small table - `tides <port> [--date YYYY-MM-DD] [--days N] [--json]` - LINZ tide predictions for a port or surf alias - `next-tide <port> [--json]` - next high tide and next low tide from now - `breaks [--json]` - list known NZ surf breaks and companion LINZ tide ports - `surf <break> [--days N] [--json]` - SwellMap forecast for a named NZ surf break - `best-break [--region auckland|coromandel|gisborne|wgtn] [--date YYYY-MM-DD] [--json]` - compare the region's morning forecast rows and pick the best average rating - `marine <area> [--json]` - NIWA marine handoff note; no no-key NIWA wave endpoint was confirmed, so use `metservice-nz marine` for key-backed MetOcean marine data ## Examples ```bash python3 skills/nz-tides-surf/scripts/cli.py levels Auckland --json python3 skills/nz-tides-surf/scripts/cli.py levels python3 skills/nz-tides-surf/scripts/cli.py tides Auckland --date 2026-05-24 python3 skills/nz-tides-surf/scripts/cli.py tides Piha --date 2026-05-24 --json python3 skills/nz-tides-surf/scripts/cli.py next-tide "Mt Maunganui" --json python3 skills/nz-tides-surf/scripts/cli.py surf Piha --days 3 python3 skills/nz-tides-surf/scripts/cli.py surf Raglan --days 3 --json python3 skills/nz-tides-surf/scripts/cli.py best-break --region auckland --json python3 skills/nz-tides-surf/scripts/cli.py breaks ``` ## Supported surf aliases Common surf questions are mapped to the closest practical source: - `Piha`, `Muriwai`, `Bethells`, `Karekare` - SwellMap Auckland West Coast forecasts, LINZ Anawhata tide companion - `Raglan`, `Manu Bay`, `Raglan Bar`, `Mussel Rock` - SwellMap Raglan forecasts, LINZ Raglan tides - `Mt Maunganui`, `Mount Maunganui`, `Tay Street` - SwellMap Tay Street forecast, LINZ Moturiki Island tides - `Lyall Bay`, `Breaker Bay`, `Makara`, `Plimmerton` - Wellington surf forecasts, LINZ Wellington tides - `Whangamata`, `Hot Water Beach`, `Kuaotunu`, `Whitianga` - Coromandel surf forecasts, nearby LINZ tide companions ## Resources - CLI entrypoint: `scripts/cli.py` - API and stability notes: `references/api-notes.md` - Related key-backed marine skill: `skills/metservice-nz/` ## Notes - LINZ tide predictions: `https://www.linz.govt.nz/products-services/tides-and-tidal-streams/tide-predictions`, using `https://www.linz.govt.nz/api/v1/tp` and `https://static.charts.linz.govt.nz/tide-tables/maj-ports/csv/...`. - LINZ standard-port levels: `https://www.linz.govt.nz/guidance/marine-information/tide-prediction-guidance/standard-port-tidal-levels`. One page, 10-second timeout, 256 KiB cap, 24-hour cache. Heights are metres on Chart Datum. MHWS, MHWN, MLWN, MLWS and the ranges are predicted reference levels. HAT and LAT are predicted extremes. MSL is derived from tidal observations; this command does not fetch the separate observation-period page and does not read gauge archives. - LINZ website content is Creative Commons Attribution 4.0 International. Attribute Toitū Te Whenua Land Information New Zealand. Do not reproduce emblems. LINZ Data Service datasets keep their own licences. - SwellMap source: `https://www.swellmap.com/surf-forecasts/new-zealand`, using the public no-login Next.js forecast payload embedded in each surf forecast page. - MetService/MetOcean source: `https://developer.metservice.com/docs/api-catalog/point-forecast-api/`; the existing `metservice-nz` skill already covers key-backed marine/wave variables. - NIWA source: `https://niwa.co.nz`; a no-key NIWA public marine wave forecast endpoint was not confirmed during implementation, so this skill does not duplicate the `metservice-nz marine` command. - Surfline source investigated: `https://www.surfline.com/surf-report`; direct CLI requests to Surfline's public JSON/search surface returned Cloudflare challenge HTML in this environment, so SwellMap is the working no-login surf source. - Magicseaweed is discontinued; no live Magicseaweed source is wired. - All times are emitted in `Pacific/Auckland`. - Endpoint shapes can change without notice because SwellMap and Surfline surfaces are public website implementation details rather than formal public APIs. - Do not commit HAR captures, screenshots, cookies, raw browser profiles, or bulky JavaScript bundles when updating this skill.