{"openapi":"3.1.0","info":{"title":"Buoycast","version":"1.0.0","description":"Pay-per-query NOAA marine buoy data, monetised via the x402 protocol (USDC on Base).","contact":{"email":"x402@crowemade.com"},"x-guidance":"Two data endpoints, both POST with a JSON body, both gated behind an x402 payment (USDC on Base). If you have a NOAA station_id, call buoy-snapshot directly. If you only have coordinates, call nearest-buoys first to find station IDs and their current readings in one call. Both endpoints validate the request body before requiring payment: a malformed or invalid request returns 400 for free; only valid, answerable requests trigger the 402 payment challenge. Payment only settles on a 200 response — a downstream NOAA failure (404/502) is never charged."},"servers":[{"url":"https://buoy-snapshot.buoycast.workers.dev"}],"paths":{"/api/v1/proxy/buoy-snapshot":{"post":{"operationId":"buoySnapshot","summary":"Latest observation from a single NOAA buoy station","description":"Latest observation from a single NOAA NDBC ocean buoy station: wave height, wave period, water temp, wind speed/direction, air pressure. Pass station_id (e.g. '44025'). Fields are null when a station's sensors don't report that variable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"station_id":{"type":"string","pattern":"^[A-Za-z0-9]{3,7}$","description":"NOAA NDBC station identifier, 3-7 alphanumeric chars. Find IDs at ndbc.noaa.gov. Example: '44025'."}},"required":["station_id"],"additionalProperties":false},"example":{"station_id":"44025"}}}},"responses":{"200":{"description":"Buoy observation","content":{"application/json":{"schema":{"type":"object","properties":{"station_id":{"type":"string","description":"The queried NDBC station ID"},"observed_at":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp of the observation"},"wave_height_m":{"type":["number","null"],"description":"Significant wave height in meters, or null if not reported"},"wave_period_s":{"type":["number","null"],"description":"Dominant wave period in seconds, or null if not reported"},"water_temp_c":{"type":["number","null"],"description":"Sea surface temperature in Celsius, or null if not reported"},"wind_speed_ms":{"type":["number","null"],"description":"Wind speed in meters/second, or null if not reported"},"wind_direction_deg":{"type":["number","null"],"description":"Wind direction in degrees true, or null if not reported"},"air_pressure_hpa":{"type":["number","null"],"description":"Sea-level air pressure in hPa, or null if not reported"},"data_age_minutes":{"type":"integer","description":"Minutes between the observation time and now"},"status":{"type":"string","enum":["ok","stale"],"description":"'stale' when data is older than 90 minutes"},"source":{"type":"string","description":"Always 'NOAA NDBC'"},"source_url":{"type":"string","format":"uri","description":"Link to the station page on ndbc.noaa.gov"},"cache_hit":{"type":"boolean","description":"Whether this response was served from cache"}},"required":["station_id","observed_at","status","source","cache_hit"]},"example":{"station_id":"44025","observed_at":"2026-07-03T16:50:00.000Z","wave_height_m":0.8,"wave_period_s":5,"water_temp_c":22.9,"wind_speed_ms":null,"wind_direction_deg":null,"air_pressure_hpa":1015.5,"data_age_minutes":25,"status":"ok","source":"NOAA NDBC","source_url":"https://www.ndbc.noaa.gov/station_page.php?station=44025","cache_hit":false}}}},"400":{"description":"Invalid or missing station_id, or malformed JSON body (never charged)"},"402":{"description":"Payment Required"},"404":{"description":"Station not found"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]}}},"/api/v1/proxy/nearest-buoys":{"post":{"operationId":"nearestBuoys","summary":"Nearest active NOAA buoy stations to a coordinate","description":"Find the nearest active NOAA buoy stations to a coordinate and return each station's current readings, sorted by distance. Pass lat and lon in decimal degrees, optional limit 1-10 (default 5). Ideal starting point when you have coordinates but not a station ID.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees. Example: 40.71"},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees. Example: -74.01"},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"Number of nearest stations to return. Default 5, max 10."}},"required":["lat","lon"],"additionalProperties":false},"example":{"lat":40.71,"lon":-74.01,"limit":5}}}},"responses":{"200":{"description":"Nearest stations with current readings","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"limit":{"type":"integer"}},"required":["lat","lon","limit"]},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"NDBC station ID"},"lat":{"type":"number","description":"Station latitude"},"lon":{"type":"number","description":"Station longitude"},"name":{"type":"string","description":"Station name"},"met":{"type":"boolean","description":"Always true — station reports meteorological data"},"distance_km":{"type":"number","description":"Distance from query point in km, 1 decimal"},"observation":{"type":["object","null"],"description":"Current reading for this station, or null if temporarily unavailable"},"cache_hit":{"type":"boolean"}},"required":["id","lat","lon","name","distance_km","cache_hit"]}},"source":{"type":"string","description":"Always 'NOAA NDBC'"},"count":{"type":"integer","description":"Number of stations returned"}},"required":["query","results","source","count"]},"example":{"query":{"lat":40.71,"lon":-74.01,"limit":5},"results":[{"id":"44065","lat":40.368,"lon":-73.701,"name":"New York Harbor Entrance - 15 NM SE of Breezy Point, NY","met":true,"distance_km":46.1,"observation":{"station_id":"44065","observed_at":"2026-07-03T16:40:00.000Z","wave_height_m":null,"wave_period_s":null,"water_temp_c":22.4,"wind_speed_ms":3,"wind_direction_deg":210,"air_pressure_hpa":1015.3},"cache_hit":false}],"source":"NOAA NDBC","count":1}}}},"400":{"description":"Invalid or missing lat/lon, or malformed JSON body (never charged)"},"402":{"description":"Payment Required"},"404":{"description":"No active stations found"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]}}}}}