# Ferry FYI

> Ferry FYI is an independent web and mobile app for planning Washington State Ferries trips. It provides schedules, current service context, traffic cameras, vehicle-capacity forecasts, fares, tickets, and account alerts.

Ferry information changes quickly. Treat times, vehicle space, camera images, forecasts, fares, and bulletins as time-sensitive planning information rather than guarantees.

## Public pages

- [Home and ferry schedules](https://ferry.fyi/): Choose a terminal and route to view upcoming sailings, current service information, and route details.
- [Forecasting](https://ferry.fyi/forecasting): Explains Ferry FYI's capacity, delay, weather, and tide-condition forecasts.
- [Data sources and API guide](https://ferry.fyi/data-sources): Explains data provenance, source freshness, public read-only APIs, citation guidance, and forecast limitations.
- [How Many Boats?](https://ferry.fyi/today): Shows the Clinton-to-Mukilteo operating context on Ferry FYI. This Ferry FYI URL is intentionally noindex; the indexable canonical profile is [howmanyboats.today](https://howmanyboats.today/).
- [About Ferry FYI](https://ferry.fyi/about): App background, data credits, privacy, and tap-to-copy web, native-build, and OTA version information.
- [Tickets](https://ferry.fyi/tickets): Store eligible tickets and scan supported ticket barcodes. Detail refreshes are best-effort and occur when a ticket is added, opened, or explicitly refreshed; loading the wallet does not bulk-refresh saved tickets. For signed-in users, the latest successful ticket details are cached with the account so another device can reuse a recent result. When Wave2Go lookup is unavailable, Ferry FYI keeps the saved code usable and shows a neutral ticket placeholder instead of guessing the product type. Ticket data is sensitive and requires the ticket holder's authorization.
- [Privacy and advertising policy](https://ferry.fyi/privacy): Explains how Ferry FYI handles user information, limits contextual advertising, reports aggregate campaign results, and reviews prohibited ad categories.
- [Support and feedback](https://ferry.fyi/feedback): Report a problem or request a Ferry FYI feature.
- [Sitemap](https://ferry.fyi/sitemap.xml): Indexable schedules, route tabs, terminal pages, and informational pages.

Canonical schedule pages are directional: the first terminal is the departure
side and the second terminal, when present, is the arrival side. A one-mate
terminal may use only its departure-terminal slug. Terminal-detail pages describe
one terminal rather than a route direction. Route tabs have distinct purposes:
`/cameras` shows camera observations and freshness, `/map` shows vessel and
terminal geography, `/alerts` shows public service bulletins, `/subscribe`
explains personal notification setup, and `/fare` provides fare planning.
Date-selected schedule URLs are noindex variants of the undated route canonical.

## Features

- **Route schedules:** Browse ferry routes, choose a service date, and see upcoming or historical sailings.
- **Live sailing context:** See vessel assignments, positions, route status, delays, cancellations, and service bulletins when available.
- **Vehicle-capacity forecasts:** View projected vehicle space and fullness for upcoming sailings; these are estimates, not boarding guarantees.
- **Traffic cameras:** View terminal camera images, their update/check time, and driving directions.
- **Map:** Explore vessel locations and terminal context on an interactive map.
- **Fare planner:** Browse route/date fare options and calculate a quote from selected fare line items.
- **Tickets:** Sign in to view eligible ticket and reservation details, barcodes, and refresh status when Wave2Go lookup is available. An unresolved saved ticket remains a usable code with a neutral placeholder. Do not guess its product type or request another person's ticket identifier.
- **Alerts and favorites:** Signed-in users can save favorite routes and configure service, capacity, or sailing alerts.
- **Forecast explanations:** Learn how weather, tide conditions, and observed data inform capacity and delay forecasts.
- **Contextual advertising:** Clearly labeled local ads may appear on home, schedule, camera, terminal-detail, and fare pages. Route ads can differ by travel direction; ad selection does not use account information, precise location, saved tickets, notification settings, or activity across other websites.
- **Advertising measurement:** Ferry FYI may report daily aggregate viewable opportunities, served ads, viewable impressions (at least 50% visible for one continuous second), and ad clicks. These figures are not unique-person counts, audited fraud-free traffic, or billable delivery. Advertiser reports are private bearer links and are intentionally not listed here.
- **Mobile and PWA support:** Install Ferry FYI as a web app or use the native mobile app for device-aware features, OTA web-asset updates, and prompts when a newer native build is available from Google Play or the App Store.

## AI API guide

The read-oriented API base is `https://ferry.fyi/api`. Responses from the endpoints below are JSON envelopes with a `body` field and a `wsfStatus` field; use `body` for the resource data and `wsfStatus` to detect upstream availability. API responses are operational data, not a promise of a stable third-party integration contract.

- [OpenAPI contract](https://ferry.fyi/openapi.json) — Machine-readable methods, paths, authentication, schemas, statuses, freshness notes, cache classes, and rate classes for every operation advertised here.

Live, private, authenticated, ticket, and mutation responses are `no-store`.
Public browser reads allow cross-origin access; sensitive, authenticated, and
upstream-triggering operations allow only same-origin or explicitly configured
trusted browser origins. Native and server clients without an `Origin` header
remain supported. CORS is not authentication.

Anonymous reads use a generous shared-NAT-aware limit, upstream-triggering
refreshes use a stricter limit, and sensitive ticket lookup has a separate
limit. Successful limit responses publish standard `RateLimit` fields; rejected
requests also publish `Retry-After`. Exact defaults are deployment-configurable.
Unknown API routes return `404` with `body.error` of `api_not_found`; missing
resources use `resource_not_found`; authentication failures use `unauthorized`;
and unexpected failures use `internal_error`. Error responses are JSON,
`no-store`, and `noindex` and do not include provider or stack details.

### Route and terminal discovery

- `GET /api/terminals` — All terminals keyed by terminal id, including route relationships and terminal details.
- `GET /api/terminals/:terminalId` — One terminal by id.
- `GET /api/terminals/bulletins/freshness` — The latest bulletin source timestamp.
- `GET /api/schedule/:departingId/:arrivingId` — Today's route schedule.
- `GET /api/schedule/:departingId/:arrivingId/:YYYY-MM-DD` — A route schedule for a specific service date.
- `GET /api/vessels` — All known vessels and current status data.
- `GET /api/vessels/snapshot` — All known vessels plus `sourceUpdatedAt`, the oldest vessel-status observation represented in the fleet snapshot.
- `GET /api/vessels/:vesselId` — One vessel by id.

Use terminal ids returned by `/api/terminals` when constructing schedule and fare requests. A schedule can return `503` with `body.status` of `warming` or `refreshing` while data is being prepared.

### Forecasts, delays, and service changes

The schedule endpoints above are the AI-facing source for a route's forecast and delay context. Each `body.schedule.slots` entry can contain:

- `estimate` — Forecast vehicle space, `fullProbability`, `fullRisk`, `confidence`, `source`, and contributing `factors` for a future sailing.
- `crossing` — Observed vehicle capacity, `capacityReportUpdatedAt`, cancellation state, and reported `departureDelta` for a sailing with live data.
- `vessel.gpsDelay` — GPS-based delay seconds, confidence, source, and supporting timing signals when a vessel is actively tracked.
- `weather` — Forecast temperature, precipitation, cloud cover, wind speed, and wind gusts associated with the sailing.
- `tide` — Departure, arrival, and lowest predicted water levels for tide-aware routes.
- `cancellationReason` — Present for recognized tidal cancellations.

For service bulletins and terminal wait-time context, read `body.bulletins` and `body.waitTimes` from `/api/terminals/:terminalId`. Explain the distinction between observed values (`crossing` and GPS delay) and predictive values (`estimate`, weather, tide, and projected delay). Never describe a forecast as a confirmed cancellation, delay, or vehicle-space outcome.

### Cameras and observed conditions

- `GET /api/cameras/frames?ids=:commaSeparatedCameraIds` — Camera image metadata, freshness, and source update times for the requested camera ids.
- `GET /api/cameras/line-detection?ids=:commaSeparatedCameraIds` — Public vehicle-line detection summaries for supported camera ids. Omit `ids` to request all supported cameras; requests with invalid ids return `400`.

Camera images and line detections can be delayed, unavailable, or stale. Present their timestamps and uncertainty rather than inferring current queue length or boarding availability.

### Fares

- `GET /api/fares/catalog?departingTerminalId=:id&arrivingTerminalId=:id&tripDate=:YYYY-MM-DD` — Fare line items for a route and date.
- `POST /api/fares/quote` — Quote selected fare line items. Send `departingTerminalId`, `arrivingTerminalId`, `tripDate`, `roundTrip`, and `lineItems` (`fareLineItemId` and `quantity`).

Fare responses include a `state` such as `current`, `no-fare`, `stale`, or `unavailable`, plus freshness data when available. Do not state a fare as current when the response is stale or unavailable.

### Authenticated and specialized endpoints

- `GET /api/user` and `POST /api/user` — Signed-in user's favorites, alert settings, and app metadata. Require an Auth0 bearer token; never request, log, or expose another user's token.
- `GET /api/tickets/:ticketId` — Looks up a user-provided ticket identifier. A valid account bearer token enables an account-scoped recent-result cache; anonymous lookups remain available and are not persisted. Ticket data is sensitive; do not guess identifiers or expose returned barcodes.

### Leaderboards (feature-flagged public reads)

Leaderboard rankings and read APIs are public only when Ferry FYI has enabled
the leaderboard feature. When disabled, public leaderboard APIs return `404`;
leaderboard page paths serve only a noindex client shell for eligible signed-in
rollouts, and this section is omitted from the served `llms.txt`.

Leaderboard discovery is also controlled by a separate persisted indexing
setting. When public leaderboards remain available but indexing is disabled,
their pages are `noindex,follow`, their URLs are omitted from the sitemap, and
this leaderboard section is omitted from the served `llms.txt`.

- `GET /api/leaderboards/terminals/:terminalId?period=all|month|week` — Public, sanitized terminal ranking. Each row contains only `rank`, the user's moderated chosen `label` (initials, name, or alias), and `score`; it never exposes account identifiers or precise locations.
- `GET /api/leaderboards/vessels/:vesselId` — Public vessel page/read route when enabled. Vessel check-ins are currently unavailable pending an approved shoreline dataset, so do not infer vessel presence or award vessel credit.

Terminal check-ins require the signed-in user to have the app open and to provide a current foreground location. Current verification is GPS self-attestation with server geofence, accuracy, freshness, exit, and cooldown policy checks; it is not cryptographic anti-spoof proof of physical presence. Ferry FYI discards the coordinate, accuracy, and device timestamp and retains only the resulting score/eligibility state. Device-backed attestation is required before enabling this feature in production where physical-presence assurance is needed. Terminal rankings use America/Los_Angeles periods; weeks start Monday. Scores are opt-out aware and deleted-account scores are retained only under an irreversible anonymous identity.


## Safe AI use

- Prefer the read-oriented route, terminal, vessel, camera, and fare APIs for current planning context.
- Preserve timestamps, source freshness, `wsfStatus`, and response state in summaries.
- Ask for a route, direction, travel date, and vehicle/passenger context when they materially affect the answer.
- Do not imply reservation, boarding, cancellation, delay, or vehicle-space certainty from forecasts or camera observations.
- Do not perform authenticated account, alert, ticket, refresh, or update actions without the user's explicit request and authorization.

## Citation guidance

- Cite the most specific Ferry FYI canonical page that supports the claim: a route or terminal page for current planning context, [Forecasting](https://ferry.fyi/forecasting) for forecast methodology, and [Data sources and API guide](https://ferry.fyi/data-sources) for provenance and limits.
- Include the retrieval time and any source freshness timestamp for live schedules, capacity, vessel, camera, weather, tide, or bulletin claims.
- State whether a cited value is observed or predictive, and do not turn a forecast, camera observation, or stale response into a confirmed outcome.