nz-tides-surf
Query New Zealand LINZ tide predictions and SwellMap surf forecasts through a lightweight read-only CLI. Use when the task involves NZ tide times, next high/low tide, surf forecasts, swell trend, or c
SKILL.mdskills/nz-tides-surf/SKILL.md
GitHubNZ 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-nzfor 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
levelsas a daily tide prediction or as a measured gauge height.levelspublishes reference heights in metres on Chart Datum.tidesremains the prediction timetable. Chart Datum is the zero of those predictions.
Preferred workflow
- Run
scripts/cli.pywith the narrowest subcommand that answers the task - Use
tidesornext-tidefor official LINZ tide predictions - Use
levelsfor published standard-port reference heights (MHWS, MHWN, MLWN, MLWS, ranges, MSL, HAT, LAT) in metres on Chart Datum - Use
surffor a specific break forecast - Use
best-breakwhen the user asks where to drive tomorrow morning - Use
breaksto see the curated surf breaks and their companion LINZ tide ports - Use
--jsonfor agent chaining, comparisons, and reports - Mention that surf ratings are SwellMap forecast snapshots,
tidesrows are official LINZ predictions, andlevelsrows are published reference heights rather than gauge observations
CLI
Run with:
python3 skills/nz-tides-surf/scripts/cli.py <command> [flags]
Commands
ports [--json]- list available LINZ tide ports and common surf aliaseslevels [port] [--json]- published LINZ standard-port tidal levels in metres on Chart Datum; omit the port to return the whole small tabletides <port> [--date YYYY-MM-DD] [--days N] [--json]- LINZ tide predictions for a port or surf aliasnext-tide <port> [--json]- next high tide and next low tide from nowbreaks [--json]- list known NZ surf breaks and companion LINZ tide portssurf <break> [--days N] [--json]- SwellMap forecast for a named NZ surf breakbest-break [--region auckland|coromandel|gisborne|wgtn] [--date YYYY-MM-DD] [--json]- compare the region's morning forecast rows and pick the best average ratingmarine <area> [--json]- NIWA marine handoff note; no no-key NIWA wave endpoint was confirmed, so usemetservice-nz marinefor key-backed MetOcean marine data
Examples
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 companionRaglan,Manu Bay,Raglan Bar,Mussel Rock- SwellMap Raglan forecasts, LINZ Raglan tidesMt Maunganui,Mount Maunganui,Tay Street- SwellMap Tay Street forecast, LINZ Moturiki Island tidesLyall Bay,Breaker Bay,Makara,Plimmerton- Wellington surf forecasts, LINZ Wellington tidesWhangamata,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, usinghttps://www.linz.govt.nz/api/v1/tpandhttps://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 existingmetservice-nzskill 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 themetservice-nz marinecommand. - 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.