NZ Ferries

Goal

Query live public ferry schedule and alert surfaces across major NZ ferry operators through a small deterministic CLI with human-readable and JSON output. Direct public HTTP/GTFS is the default; optional --browser probes Fullers public timetable pages with CloakBrowser while keeping AT GTFS fallback. No login, booking, payment, or CAPTCHA bypass.

This skill is deliberately separate from at-transport:

• nz-ferries = sailing schedules, fare snapshots, availability signals, and service alerts across NZ ferry operators
• at-transport = live Auckland Metro public transport data, including ferry route_type=4 vehicle positions and stop departures

Use this when

• A user asks for Cook Strait ferry sailings between Wellington and Picton
• A user wants a combined Interislander + Bluebridge view for a travel date
• A user asks for SeaLink Waiheke Island or Great Barrier Island vehicle/passenger ferry times
• A user asks for Fullers360/AT Metro Auckland ferry schedules such as Devonport, Waiheke, Half Moon Bay, Hobsonville, Bayswater, Birkenhead, Northcote, Pine Harbour, West Harbour, or Rangitoto
• A user asks for the next Devonport ferry, the last Waiheke ferry tonight, or current Auckland ferry cancellations
• A user wants current ferry operator service alerts, reminders, delays, cancellations, or weather notices
• A workflow needs lightweight machine-readable ferry sailing data from public operator surfaces

Do not use this for

• Booking, payment, checkout, login, account, ticket, refund, or booking-management actions
• Live Auckland Transport ferry vehicle positions or full AT public transport stop-departure workflows; use at-transport
• High-volume scraping or building a historical ferry timetable dataset
• Fullers360/AT Metro ferry real-time vehicle tracking; that is already covered by AT GTFS-RT in at-transport
• Guaranteed availability claims; public schedule/booking-slot surfaces can change after the CLI query

Preferred workflow

1. Run scripts/cli.py with the narrowest subcommand that answers the task
2. Use cook-strait for Wellington/Picton planning because it combines Interislander and Bluebridge
3. Use sailings <route> --operator <operator> when a specific ferry company is known
4. Use next <route> for the next upcoming sailings from the current NZ time
5. Use alerts before presenting travel advice for a date-sensitive trip
6. Use --browser with Fullers routes only when you want a public Fullers timetable-page probe; if it is blocked, trust the AT GTFS fallback and report the blocked status
7. Use --json for agent chaining, comparisons, or structured reports
8. Mention the source operator and that results are public read-only snapshots

CLI

Run with:

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

Commands

• operators [--json] - list supported ferry operators and coverage
• routes [--operator OPERATOR] [--json] - list route IDs and aliases
• sailings <route> [--date YYYY-MM-DD] [--operator OPERATOR] [--json] [--browser] - sailings on a date; --browser probes Fullers public timetable page and keeps AT GTFS fallback
• next <route> [--operator OPERATOR] [--limit N] [--json] [--browser] - next few upcoming sailings from now; --browser probes Fullers public timetable page when applicable
• alerts [--operator OPERATOR] [--json] - current public service alerts/reminders
• cook-strait [--date YYYY-MM-DD] [--direction wellington-picton|picton-wellington|both] [--operator OPERATOR] [--json] - combined Cook Strait view

Examples

python3 skills/nz-ferries/scripts/cli.py operators
python3 skills/nz-ferries/scripts/cli.py routes --operator sealink --json
python3 skills/nz-ferries/scripts/cli.py cook-strait --date 2026-05-24 --json
python3 skills/nz-ferries/scripts/cli.py sailings wellington-picton --operator interislander --date 2026-05-24
python3 skills/nz-ferries/scripts/cli.py sailings wellington-picton --operator bluebridge --date 2026-05-24 --json
python3 skills/nz-ferries/scripts/cli.py sailings auckland-waiheke --operator sealink --date 2026-05-24
python3 skills/nz-ferries/scripts/cli.py sailings auckland-devonport --operator fullers --date 2026-05-24 --json --browser
python3 skills/nz-ferries/scripts/cli.py sailings auckland-waiheke --operator fullers --date 2026-05-24 --json
python3 skills/nz-ferries/scripts/cli.py next auckland-devonport --operator fullers
python3 skills/nz-ferries/scripts/cli.py next auckland-waiheke --operator sealink --limit 5
python3 skills/nz-ferries/scripts/cli.py alerts --operator fullers
python3 skills/nz-ferries/scripts/cli.py alerts --json

Notes

• Upstream sources: SeaLink (sealink.co.nz), Interislander/KiwiRail (interislander.co.nz), Bluebridge/StraitNZ (bluebridge.co.nz), Fullers360 (fullers.co.nz and pim-mobile.fullers.co.nz for discovery context), and Auckland Transport public GTFS/GTFS-RT for Fullers/AT Metro ferry schedules and alerts.
• SeaLink uses a public schedule endpoint that returns sailing times, ferry names, availability/status, remaining passenger spaces, and fare snapshots for a query basket. The CLI uses one car+driver and one adult only to expose public fare/availability fields; it does not create or mutate bookings.
• Interislander uses the public ferry timetable page and public disruption endpoint. The timetable page publishes departure times and says crossings take about 3.5 hours, so arrival times are estimated from that duration.
• Bluebridge uses the public timetable and service-alert pages. The CLI filters known day restrictions such as "not available on weekends" from the published timetable notes.
• Fullers360 app and website timetable endpoints were reverse-engineered, but direct stdlib requests hit Radware/hCaptcha validation. The shipped Fullers implementation uses AT's public static GTFS zip for scheduled sailings and AT GTFS-RT service alerts for cancellations and disruptions. Optional --browser on sailings/next probes the public Fullers timetable page with CloakBrowser and records browser_probe.status as loaded or blocked; it never solves CAPTCHA/PerfDrive/hCaptcha and AT GTFS remains the structured source.
• Fullers fare snapshots are not implemented because the Fullers website/app fare/timetable fragments are browser-gated from direct CLI fetches.
• No operator account cookie, browser session, booking mutation, or payment action is required. AT Metro/Fullers data commands require a user-supplied AT_API_KEY; the repository does not bundle the subscription key.
• Endpoint shapes can change without notice because these are public website surfaces rather than official stable APIs.
• API and stability notes: references/api-notes.md
• CLI entrypoint: scripts/cli.py