# Ferry FYI

> Ferry FYI is an independent web and mobile app for planning Washington State Ferries trips using schedules, service bulletins, vessel positions, cameras, capacity forecasts, fares, tickets, and account alerts.

This file is task-oriented documentation for readers and AI tools, not a search-ranking mechanism. Ferry information is time-sensitive planning context, not a boarding guarantee.

## Tasks

- **Plan a crossing:** Use [ferry schedules](https://ferry.fyi/) to choose departure and arrival terminals, a service date, and vehicle or passenger travel. Compare WSF wait reports with listed sailings, then check cancellations, delays, cameras and vehicle-space forecasts. Past-sailing reports are confirmed observations, not forecasts. Small timing differences may fall within the on-time tolerance. Arrival advice and departure countdowns are not measured queue waits; retain report timestamps and check the terminal named in route-wide alerts.
- **Estimate which sailing to catch:** Use the explicit form on a [Navigation page](https://ferry.fyi/seattle/bainbridge/navigation) for driving, walking, cycling, or transit. Availability depends on provider configuration. Estimates omit booth-line, parking, and reservation delays; probabilities are modeled, not measured boarding success. Never automate precise-origin requests.
- **Check conditions:** Open a route's cameras, map, or [WSF alerts](https://ferry.fyi/clinton/alerts). Public service alerts describe reported disruptions and advisories; they are separate from personal alert setup and exclude Ferry Riders Opinion Group promotions. Preserve alert severity, route scope, and source time; unavailable or pending reports are not an all-clear. Cameras show departure-terminal snapshots, not live video or measured waits; image-check times are distinct from source-image changes, and holding capacities are static references. Camera observations, vessel reports, and forecasts answer different questions; do not treat them as interchangeable.
- **Find terminal details:** Use a [terminal page](https://ferry.fyi/seattle/terminal) for its address and directions to the dock, parking, transport connections, accessibility, facilities, and route-planning links. WSF arrival guidance is general advice, not a live queue measurement; retain its source date and confirm changeable details with the operator.
- **Estimate a fare:** Compare default adult passenger and standard vehicle-with-driver one-way and round-trip rates, then calculate a custom fare. Select quantities from the route/date catalog; defaults are not personalized quotes or eligibility decisions. Free means an explicit zero fare, not unavailable pricing; a free departure does not establish a free return.
- **Manage personal travel:** [Tickets](https://ferry.fyi/tickets), favorites, and personal alerts require the holder's authorization. Unavailable ticket lookup does not invalidate a saved code; do not guess its product type or identifiers. Account settings require sign-in. iOS uses password login; existing Google users can use [account migration](https://ferry.fyi/ios), not automatic identity linking.
- **Install or get help:** Use [Install](https://ferry.fyi/install), [Support](https://ferry.fyi/support), or [About](https://ferry.fyi/about). [Supporter](https://ferry.fyi/supporter) is optional; prices and availability come from the current storefront. Read [Privacy](https://ferry.fyi/privacy) and [Terms](https://ferry.fyi/terms) for account, advertising, and subscription policies.

Canonical schedule pages are directional: the first terminal is the departure side and the second is the arrival side. A one-mate terminal may use only its departure slug. Terminal-detail pages describe one terminal. `/cameras` shows camera observations and freshness; `/map` shows vessels and terminals; `/alerts` shows public bulletins; `/subscribe` covers personal alerts; `/fare` covers fare planning. API requests use terminal ids, not page slugs.

## Reference pages

- [Forecasting](https://ferry.fyi/forecasting): Capacity, delay, weather, and tide methodology and limitations.
- [Data sources and API guide](https://ferry.fyi/data-sources): Provenance, freshness, API use, and citation guidance.
- [Clinton–Mukilteo operating context](https://ferry.fyi/today): Route operating information.
- [Sitemap](https://ferry.fyi/sitemap.xml): Public schedules, terminal pages, and informational pages.

## Freshness

- Preserve the service date, route direction, retrieval time, source timestamps, response state, and `wsfStatus`. Interpret ferry dates and times in America/Los_Angeles.
- Public page snapshots are reused within 03:00 and 15:00 Pacific refresh windows. Source observations may be older than the page snapshot; browser updates and live APIs may be fresher.
- Vessel snapshot `sourceUpdatedAt` is the oldest vessel-status observation represented, not a guarantee that every vessel has just updated. Camera images and occupancy states can be delayed, stale, or unavailable.
- Fare states include `current`, `no-fare`, `stale`, and `unavailable`. Never present stale or unavailable fare data as current. Schedule `503` responses can report `body.status` of `warming` or `refreshing`; do not invent missing results.

## AI API guide

Base: `https://ferry.fyi/api`. JSON envelopes contain `body` (resource data) and `wsfStatus` (upstream availability). These are operational APIs, not a guaranteed stable third-party integration contract. The [OpenAPI contract](https://ferry.fyi/openapi.json) documents schemas, authentication, statuses, cache rules, freshness, and rate classes.

Live, private, authenticated, ticket, and mutation responses are `no-store`. Public reads permit cross-origin browser access; sensitive, authenticated, and upstream-triggering operations restrict browser origins. CORS is not authentication. Native/server clients without an `Origin` header remain supported.

Respect deployment-configurable rate limits. Anonymous reads, upstream-triggering refreshes, and sensitive ticket lookups have separate limits. Check `RateLimit` and, on rejection, `Retry-After`. Unknown routes use `api_not_found`, missing resources `resource_not_found`, auth failures `unauthorized`, and unexpected failures `internal_error` in `body.error`; error responses are JSON, `no-store`, and `noindex`.

### Route and terminal discovery

- `GET /api/terminals` — Terminals keyed by id, route relationships, and public details. Public coordinates describe docks; private booth settings are not exposed.
- `GET /api/terminals/:terminalId` — One terminal, including `body.bulletins` and `body.waitTimes`.
- `GET /api/terminals/bulletins/freshness` — Latest bulletin source timestamp.
- `GET /api/schedule/:departingId/:arrivingId` — Today's directional schedule.
- `GET /api/schedule/:departingId/:arrivingId/:YYYY-MM-DD` — Schedule for a service date.
- `GET /api/vessels` — Known vessels and current status.
- `GET /api/vessels/snapshot` — Fleet data with `sourceUpdatedAt`.
- `GET /api/vessels/:vesselId` — One vessel.

Discover terminal ids before constructing schedule or fare requests.

### Forecasts, delays, and service changes

Read `body.schedule.slots` for:

- `estimate`: Predicted vehicle space, `fullProbability`, `fullRisk`, confidence, source, and factors.
- `crossing`: Observed capacity, `capacityReportUpdatedAt`, cancellations, and reported `departureDelta`.
- `vessel.gpsDelay`: GPS-derived delay seconds, confidence, source, and timing signals.
- `weather`, `tide`, and `cancellationReason`: Forecast conditions and recognized tidal cancellations.

Distinguish observations from predictions. Vessel status can concern a different trip; sailing-specific reports take precedence over planned assignments. Demand factors apply to the stated direction and period, not the reverse route or future trips. An initial all-open capacity placeholder is not proof that a terminal is empty. Forecasts are not confirmed vehicle-space, delay, or cancellation outcomes.

### Cameras and observed conditions

- `GET /api/cameras/frames?ids=:commaSeparatedCameraIds` — Image metadata and freshness for discovered camera ids.
- `GET /api/cameras/line-detection?ids=:commaSeparatedCameraIds` — Spatial occupancy states: `empty`, `minority_full`, `majority_full`, or `full`. Omit `ids` for all supported cameras; invalid ids return `400`.

Do not convert occupancy states or images into exact vehicle counts, queue lengths, or boarding predictions.

### Fares

- `GET /api/fares/catalog?departingTerminalId=:id&arrivingTerminalId=:id&tripDate=:YYYY-MM-DD` — Route/date fare line items and optional `defaultRates` comparisons. Preserve each amount's state and freshness; `null` means unavailable, not zero. Use echoed trip mode and official totals, never double a fare to infer a round trip.
- `POST /api/fares/quote` — Calculate selected quantities; send `departingTerminalId`, `arrivingTerminalId`, `tripDate`, `roundTrip`, and `lineItems` containing `fareLineItemId` and `quantity`.

### Examples

Public discovery and a Clinton-to-Mukilteo schedule:

```http
GET https://ferry.fyi/api/terminals
GET https://ferry.fyi/api/schedule/5/14
```

For a quote, replace `YYYY-MM-DD` with the selected service date and use a `fareLineItemId` from that route/date catalog:

```http
POST https://ferry.fyi/api/fares/quote
Content-Type: application/json

{
  "departingTerminalId": "5",
  "arrivingTerminalId": "14",
  "tripDate": "YYYY-MM-DD",
  "roundTrip": false,
  "lineItems": [{ "fareLineItemId": 1, "quantity": 1 }]
}
```

### Authenticated and sensitive operations

Account operations require the owner's Auth0 bearer token. Never request, log, retain, or expose another user's token. These entries describe capabilities, not permission to perform them.

- `GET /api/user` and `POST /api/user` — Owner's favorites, alerts, and app metadata.
- `DELETE /api/user` — Permanent deletion, requiring exactly `{ "confirmation": "DELETE" }`. Never initiate account deletion for a user.
- `GET /api/supporter` — Owner's Supporter status and checkout availability.
- `PUT /api/supporter/preferences` — Owner's voluntary contextual-ad preference; does not change billing.
- `POST /api/supporter/reconcile` — Recheck the owner's subscription following their own purchase or restore.
- `POST /api/supporter/management` — Short-lived, single-use billing-management destination. Never request, follow, retain, or expose it for a user.
- `GET /api/tickets/:ticketId` — Holder-authorized sensitive lookup. A valid bearer token permits account-scoped recent-result caching; anonymous lookups are not persisted. Never guess identifiers or expose barcodes.


### Leaderboards (feature-flagged public reads)

Availability requires the leaderboard feature; disabled APIs return `404`. A separate persisted indexing setting controls discovery: when the feature or indexing is disabled, this section is omitted from served `llms.txt`, and leaderboard pages are noindex rather than advertised public search pages.

- `GET /api/leaderboards/terminals/:terminalId?period=all|month|week` — Public ranking containing only `rank`, moderated `label`, and `score`; no account identifiers or precise locations. Periods use America/Los_Angeles; weeks start Monday.
- `GET /api/leaderboards/vessels/:vesselId` — Public vessel ranking when enabled; manual vessel check-in is an explicit signed-in action, not automatic vessel detection or boarding proof.

Manual check-ins require fresh foreground location and server policy checks. GPS self-attestation is not cryptographic proof of presence; device-backed attestation is required where that assurance is needed. Submitted coordinates are discarded after verification. Eligible native builds may offer opt-in automatic check-ins, off by default and unavailable on web/PWA; candidates expire after 12 hours. Do not automate enrollment or location requests. Scores respect opt-out; retained deleted-account scores use irreversible anonymous identities.


## Safe AI use

- Prefer public planning reads. Ask for route, direction, travel date, and vehicle/passenger context when they materially change the answer.
- Never promise boarding, reservations, available vehicle space, or confirmed delays/cancellations from forecasts or camera observations. Missing data stays unknown.
- Navigation origins and typed suggestions are sensitive and sent transiently to Google when configured. Shared links and browser history can contain an address fragment; never expose it without the user's intent or automate precise-origin requests. Navigation advertising uses only the selected departure terminal, never the starting address or coordinates.
- Do not perform authenticated account, alert, ticket, refresh, or update actions without the user's explicit request and authorization. Do not infer account existence from email or link identities merely because emails match.
- Never initiate subscription purchase, restore, cancellation, refund, billing management, or account deletion for a user. Keep private advertiser-report bearer links and other credentials out of summaries and citations.

## Citation guidance

- Cite the most specific Ferry FYI canonical route or terminal page supporting the claim. Use [Forecasting](https://ferry.fyi/forecasting) for methodology and [Data sources and API guide](https://ferry.fyi/data-sources) for provenance and limits.
- Include retrieval time and relevant source freshness timestamps for live schedule, capacity, vessel, camera, weather, tide, and bulletin claims.
- Identify observed versus predictive values, qualify stale or unavailable data, and never turn an estimate into a confirmed outcome.