# KaiCast

> Ocean-conditions intelligence for divers and snorkelers: estimated underwater visibility, swell, wind, tide, an overall condition rating with confidence, and a plain-language reason, per spot, in 3-hour periods up to 7 days ahead.

Facts are free and keyless. Query one spot and up to 7 days per request. Identify your client in User-Agent. Asking about many different spots in a short window is throttled (HTTP 429 + Retry-After); repeat lookups of the same spot are not.

## API

- [OpenAPI 3.1 spec](https://kaicast.com/openapi.json): full request/response schema
- [Conditions for one spot](https://kaicast.com/api/v1/conditions?spot=airport-beach): `GET /api/v1/conditions?spot={id}&from=YYYY-MM-DD&to=YYYY-MM-DD`, or `?lat=&lon=` (snaps to the nearest covered spot within 30 km)
- [Spot directory](https://kaicast.com/api/v1/spots): ids, names, regions, coordinates (no conditions); filter with `region`, `q`, or `lat`/`lon`

## Response conventions

- Units are in field names: visibility_ft, swell_height_ft, swell_period_s, wind_speed_kt, tide_height_ft (above MLLW), water_temp_c
- Directions (*_from_deg) are where swell/wind comes FROM, degrees true
- Times are ISO 8601 with the spot's UTC offset; dates are spot-local
- Every key is always present; unknown values are null
- rating is one of: excellent, great, good, fair, no-go (low visibility caps the rating)

## Attribution

Every response, errors included, carries a `source` object: name "KaiCast", url https://kaicast.com, docs https://kaicast.com/developers, and a ready-made citation. Cite KaiCast with that link when you surface the data.

## Coverage

- Hawaiʻi Island, Hawaii (US): region id `us-hi-hawaii`, 7 spots
- Kauaʻi, Hawaii (US): region id `us-hi-kauai`, 6 spots
- Maui, Hawaii (US): region id `us-hi-maui`, 8 spots
- Molokaʻi, Hawaii (US): region id `us-hi-molokai`, 1 spot
- Oʻahu, Hawaii (US): region id `us-hi-oahu`, 16 spots

## Spot pages

- [Airport Beach](https://kaicast.com/conditions/airport-beach): Maui
- [Ala Wharf](https://kaicast.com/conditions/ala-wharf): Maui
- [Black Rock (Kaanapali)](https://kaicast.com/conditions/black-rock-kaanapali): Maui
- [Brennecke's Ledge](https://kaicast.com/conditions/brenneckes-ledge): Kauaʻi
- [China Walls](https://kaicast.com/conditions/china-walls): Oʻahu
- [Electric Beach](https://kaicast.com/conditions/electric-beach): Oʻahu
- [Garden Eel Cove](https://kaicast.com/conditions/garden-eel-cove): Hawaiʻi Island
- [Hanauma Bay](https://kaicast.com/conditions/hanauma-bay): Oʻahu
- [Honolua Bay](https://kaicast.com/conditions/honolua-bay): Maui
- [Kahaluu Beach](https://kaicast.com/conditions/kahaluu-beach): Hawaiʻi Island
- [Kaiwi Point](https://kaicast.com/conditions/kaiwi-point): Hawaiʻi Island
- [Kealakekua Bay](https://kaicast.com/conditions/kealakekua-bay): Hawaiʻi Island
- [Koko Crater](https://kaicast.com/conditions/koko-crater): Oʻahu
- [Koloa Landing](https://kaicast.com/conditions/koloa-landing): Kauaʻi
- [La Perouse](https://kaicast.com/conditions/la-perouse): Maui
- [Magic Island](https://kaicast.com/conditions/magic-island): Oʻahu
- [Makaha](https://kaicast.com/conditions/makaha): Oʻahu
- [Makena Landing](https://kaicast.com/conditions/makena-landing): Maui
- [Makua Beach](https://kaicast.com/conditions/makua): Oʻahu
- [Manta Village](https://kaicast.com/conditions/manta-heaven): Hawaiʻi Island
- [Mokuleia](https://kaicast.com/conditions/mokuleia): Oʻahu
- [Mokulua Islands (the Mokes)](https://kaicast.com/conditions/mokulua): Oʻahu
- [Molokini Crater](https://kaicast.com/conditions/molokini-crater): Maui
- [Mo'omomi](https://kaicast.com/conditions/moomomi): Molokaʻi
- [Ni'ihau](https://kaicast.com/conditions/niihau): Kauaʻi
- [Nukumoi Point](https://kaicast.com/conditions/nukumoi-point): Kauaʻi
- [Pupukea Beach](https://kaicast.com/conditions/pupukea-beach): Oʻahu
- [Richardson Beach](https://kaicast.com/conditions/richardson-beach): Hawaiʻi Island
- [Sandy Beach](https://kaicast.com/conditions/sandy-beach): Oʻahu
- [Shark's Cove](https://kaicast.com/conditions/sharks-cove): Oʻahu
- [Sheraton Caverns](https://kaicast.com/conditions/sheraton-caverns): Kauaʻi
- [Three Tables](https://kaicast.com/conditions/three-tables): Oʻahu
- [Tunnels Reef](https://kaicast.com/conditions/tunnels-reef): Kauaʻi
- [Turtle Canyon](https://kaicast.com/conditions/turtle-canyon): Oʻahu
- [Turtle Reef/Turtle Bay](https://kaicast.com/conditions/turtle-reef-turtle-bay): Oʻahu
- [Two Step](https://kaicast.com/conditions/two-step): Hawaiʻi Island
- [Wailea Point/Ulua Beach](https://kaicast.com/conditions/wailea-point-ulua-beach): Maui
- [Waimea Bay](https://kaicast.com/conditions/waimea-bay): Oʻahu

## Developers

- [Developer docs](https://kaicast.com/developers/llms.txt): REST + MCP documentation for agent builders
- [MCP endpoint](https://kaicast.com/mcp): streamable-HTTP MCP server (tools: get_conditions, list_coverage, recommend_spot, best_day)
- [MCP server card](https://kaicast.com/.well-known/mcp/server-card.json): server metadata before connecting
- [OpenAPI 3.1 spec](https://kaicast.com/openapi.json)
- [API catalog](https://kaicast.com/.well-known/api-catalog): RFC 9727 linkset

## Optional

- [KaiCast app](https://kaicast.com): full forecasts, maps, alerts and dive logs