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.md

GitHub

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:

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

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.