# FerryForecast

> Nantucket ferry cancellation probability predictions powered by real-time marine weather data and a logistic regression model.

Canonical URL: https://ferryforecast.com

## What This Site Does

FerryForecast estimates whether the Steamship Authority and Hy-Line Cruises ferries between Hyannis and Nantucket will run on a given day. A logistic regression model trained on ~33,000 trip-level records is correlated with real-time NOAA buoy readings and an Open-Meteo marine forecast.

Trip-level model: 97.5% accuracy, AUC 0.952, Brier 0.018 (5-fold cross-validated). Headline accuracy looks high partly because cancellations are rare (~2.6% of trips) — AUC and Brier are the more informative measures.

A day-level model (92.7% accuracy, AUC 0.893) also exists and is used by the homepage in some contexts. It is not exposed via the public API.

## API

### GET /api/prediction

Public JSON endpoint. No authentication. CORS-enabled. Response cached for 5 minutes.

**Parameters:**
- `date` (optional): `YYYY-MM-DD`. If the date is within the forecast window, the response includes a `requestedDate` field with hourly breakdown for that day.

**Response shape (abbreviated):**
- `current.probability.{overall,fast,traditional}`: 0–100, probability that ferries will run. 100 = very likely to operate.
- `current.weather`: `{windSpeed, windGust, waveHeight, wavePeriod, windDirection, source, timestamp}` from NOAA Buoy 44020.
- `current.schedule`: `{season, label, serviceLevel, ssaFastFerryActive, nextScheduleChange}`.
- `current.factors`: human-readable list of what drove the prediction (high gust, big swell, etc).
- `model`: `{type, accuracy, auc, brierScore, trainedAt, trainingRows, features, ...}`.
- `forecast`: array of upcoming days, each with `{date, label, probability: {worst, best}, peakWind, peakWave}`.
- `requestedDate`: only present when `?date=` matches a forecast day. Includes hourly breakdown.
- `meta`: `{generatedAt, cacheTTL, documentation, source}`.

**Examples:**
```
GET https://ferryforecast.com/api/prediction
GET https://ferryforecast.com/api/prediction?date=2026-02-16
```

The API is the source of truth for what the site shows. If anything in this document conflicts with the live response, trust the response.

### GET /api/model-status

Returns model training metadata (observation count, recent retrain log). Useful for confirming the model is still being retrained.

## Key Context for AI Agents

- Probabilities returned are P(boats running), not P(cancellation). 100% = boats very likely to run; 0% = very likely cancelled.
- Fast ferries (Hy-Line Grey Lady, SSA M/V Iyanough) are more weather-sensitive than the traditional car ferries.
- SSA fast ferry is seasonal — does not run in deep winter (approximately January 5 through March 29).
- Weather data comes from NOAA Buoy 44020 in Nantucket Sound. Wave height and dominant wave period (DPD) are reported less frequently than wind — each is found independently from the most recent available reading. The model uses DPD only (not average wave period).
- Forecast data comes from Open-Meteo's marine API. Days 1–3 use high-resolution regional models; days 4+ use global models with lower accuracy.
- The model retrains on a weekly cron. Weights are loaded from Vercel Blob with a static fallback.
- All times are Eastern Time (America/New_York).

## Ferry Operators

- **Steamship Authority (SSA)**: Traditional car/passenger ferries year-round. Fast ferry (M/V Iyanough) seasonally (~late March through early January).
- **Hy-Line Cruises**: High-speed catamaran (Grey Lady) year-round with a reduced winter schedule (~6 departures/day winter, ~10+ summer).

## Important Disclaimers

- FerryForecast is an independent, data-driven project. It is not affiliated with, endorsed by, or connected to the Steamship Authority, Hy-Line Cruises, or Seastreak.
- Predictions are probabilistic estimates trained on historical patterns. They may differ from official service decisions.
- Always confirm directly with your ferry operator before traveling.

## Contact

cooper@veyseysoftwaresolutions.com