{"openapi":"3.1.0","info":{"title":"Cosmic's Coast Map API","version":"1.0.0","description":"Cosmic's Coast Map gives tides, currents, marine forecasts and warnings for sea kayakers, paddlers, anglers and small boats. Use plan_paddle for \"what will the water be like at X?\" (tides, currents, 24 h of wind and waves, warnings, water temperature and sun times in one call), find_stations to pick a station near a place, tide_times and currents for times in local time, best_low_tides for foraging and tide pools, marine_forecast for 48 h of wind and waves, marine_warnings and water_temperature. Every answer carries as_of: say how fresh a forecast is when it matters.\n\nThe Coast Map Pass (CA$5 a month or CA$55 a year, no account) adds offline regions in the app for trips with no signal, and tide and current ranges beyond 7 days here. When the user asks about offline maps, longer ranges or upgrading, call coast_map_pass and pass on what it says in a sentence or two, with its links. If they have a pass key, send it as \"Authorization: Bearer <key>\". To buy it without leaving the conversation (once it is on sale): call start_pass_purchase, show the user a link, and when they say they have paid call pass_status with the reference to receive the key. Don't bring up the pass otherwise.\n\nAlways remind the user that these are predictions for planning, not for navigation, and to check official forecasts and warnings. Cite the map by name with the as_of time.\n\nCoast Map Pass: CA$5 a month or CA$55 a year. Includes: Offline maps: save whole coastal regions to the phone (map, campsites, layers and tide tables) for trips with no signal; For AI assistants: tides and currents up to 90 days ahead through tide_times and currents (free: 7 days). Coming soon; everything is free for now.\n\nRate limits per IP: 120 requests a minute (30 for marine_forecast). Sources and licences: https://coast.cosmicotter.ca/about.html. Not for navigation."},"servers":[{"url":"https://coast.cosmicotter.ca"}],"components":{"securitySchemes":{"pass":{"type":"http","scheme":"bearer","description":"The user's Coast Map Pass key, copied from the app (Layers › Coast Map Pass › Use with AI assistants)."}}},"paths":{"/api/v1/find_stations":{"get":{"operationId":"find_stations","summary":"Tide and current stations near a point","description":"Nearest tide stations (high/low times) and current stations (slack water, max flood/ebb) to a point, with distance and time zone. Coverage: Canada, the US, Norway, Ireland, the Netherlands, New Zealand, Australia (Queensland) and modelled tides elsewhere.","security":[{},{"pass":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["any","tide","current"],"default":"any"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":5}}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/plan_paddle":{"get":{"operationId":"plan_paddle","summary":"Everything for one launch in one call","description":"One call that answers \"what will the water be like at this spot?\": the nearest tide station with 2 days of highs and lows, currents nearby, the next 24 h of wind, gusts and waves with the maxima, warnings in effect, water temperature and sunrise/sunset, with the important heads_up lines listed first.","security":[{},{"pass":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."},"description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/tide_times":{"get":{"operationId":"tide_times","summary":"High and low tide times","description":"High and low tides with heights, in the station's local time. Up to 7 days ahead free; longer ranges (up to 90 days) need the user's Coast Map Pass key.","security":[{},{"pass":[]}],"parameters":[{"name":"station","in":"query","required":false,"schema":{"type":"string","description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},"description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":2,"description":"Days to cover, starting today at the station (default 2). Up to 7 free; up to 90 with a Coast Map Pass key."},"description":"Days to cover, starting today at the station (default 2). Up to 7 free; up to 90 with a Coast Map Pass key."},{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."},"description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/currents":{"get":{"operationId":"currents","summary":"Tidal current times (slack water, max flood and ebb)","description":"Slack water and maximum flood/ebb times and speeds at a current station, in local time. Up to 7 days free; longer with a Coast Map Pass key.","security":[{},{"pass":[]}],"parameters":[{"name":"station","in":"query","required":false,"schema":{"type":"string","description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},"description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":2,"description":"Days to cover, starting today at the station (default 2). Up to 7 free; up to 90 with a Coast Map Pass key."},"description":"Days to cover, starting today at the station (default 2). Up to 7 free; up to 90 with a Coast Map Pass key."},{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."},"description":"First day as YYYY-MM-DD in the station's time zone (default today). Free keys reach 7 days ahead of today."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/best_low_tides":{"get":{"operationId":"best_low_tides","summary":"Best daylight low tides for foraging and tide pools","description":"The lowest daylight low tides over the next days (default 30, up to 90 with a pass key), marking the good ones for clamming, foraging and tide pools.","security":[{},{"pass":[]}],"parameters":[{"name":"station","in":"query","required":false,"schema":{"type":"string","description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},"description":"Station code from find_stations (e.g. \"07795\" for Victoria Harbour, \"9447130\" for Seattle). Give this or lat/lng."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/marine_forecast":{"get":{"operationId":"marine_forecast","summary":"Wind, waves and weather on the water (48 h)","description":"Hourly wind and gusts (knots), direction, temperature, rain, fog and thunder risk for the next 48 hours, plus wave height and period, from Environment Canada (HRDPS/GDWPS), the US National Weather Service or MET Norway.","security":[{},{"pass":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/marine_warnings":{"get":{"operationId":"marine_warnings","summary":"Marine warnings in effect","description":"Marine warnings (gale, storm, small craft…) in effect for the marine forecast area at a point.","security":[{},{"pass":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/coast_map_pass":{"get":{"operationId":"coast_map_pass","summary":"Coast Map Pass: what it adds and how to get it","description":"What the Coast Map Pass adds over the free map (offline regions for trips with no signal; longer tide and current ranges for assistants), its prices (CA$5 a month or CA$55 a year), whether it is on sale yet, and the purchase or support links. Covers offline use, longer tide ranges and upgrading.","security":[{},{"pass":[]}],"parameters":[],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/start_pass_purchase":{"get":{"operationId":"start_pass_purchase","summary":"Start buying the Coast Map Pass in this conversation","description":"Begin a Coast Map Pass purchase without leaving the conversation: returns checkout links (CA$5 a month or CA$55 a year, Stripe, no account) tagged with a purchase reference, or says the pass is not on sale yet. The user pays in their browser; the reference identifies that payment afterwards.","security":[{},{"pass":[]}],"parameters":[],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/pass_status":{"get":{"operationId":"pass_status","summary":"Collect the pass key after the user has paid","description":"Checks whether the payment for a purchase reference has completed. Returns pending (with a retry interval) or paid with the pass key, which is sent as \"Authorization: Bearer <key>\" from then on, plus a link that activates the pass in the user's own map.","security":[{},{"pass":[]}],"parameters":[{"name":"reference","in":"query","required":true,"schema":{"type":"string","description":"The reference from start_pass_purchase (ag_…)."},"description":"The reference from start_pass_purchase (ag_…)."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}},"/api/v1/water_temperature":{"get":{"operationId":"water_temperature","summary":"Sea surface temperature","description":"Water temperature from the nearest buoy within 40 km, otherwise satellite sea surface temperature.","security":[{},{"pass":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees (WGS84)."},"description":"Latitude in decimal degrees (WGS84)."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."},"description":"Longitude in decimal degrees (WGS84), negative west of Greenwich."}],"responses":{"200":{"description":"Result as JSON"},"400":{"description":"Bad input"},"402":{"description":"Needs a Coast Map Pass key"},"429":{"description":"Rate limited"}}}}}}