└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | # Spitcast API Documentation
  2 | 
  3 | Welcome to the Spitcast API. This API provides surf forecasts and ocean condition data for California surf spots. It includes data sourced from NOAA and Spitcast's proprietary forecast engine.
  4 | 
  5 | ---
  6 | 
  7 | ## Endpoints
  8 | 
  9 | ### 🌊 Surf Spots
 10 | 
 11 | Get a (growing) list of California surf spots for which Spitcast provides forecasts.
 12 | 
 13 | **Endpoint:**  
 14 | `https://api.spitcast.com/api/spot`
 15 | 
 16 | ---
 17 | 
 18 | ### 📈 Surf Forecast
 19 | 
 20 | Get Spitcast's surf forecast for a specific spot and date. Forecasts include wave height and shape quality.
 21 | 
 22 | **Endpoint Format:**  
 23 | `https://api.spitcast.com/api/spot_forecast/{spot_id}/{year}/{month}/{day}`
 24 | 
 25 | **Example:**  
 26 | `https://api.spitcast.com/api/spot_forecast/1/2025/3/14`
 27 | 
 28 | **Shape Values:**
 29 | - `0.0` = Poor  
 30 | - `0.5` = Poor-Fair  
 31 | - `1.0` = Fair  
 32 | - `>1.0` = Good
 33 | 
 34 | ---
 35 | 
 36 | ### 🌊 Swell Forecast
 37 | 
 38 | NOAA WAVEWATCH III data, regionally parsed by county. Shows offshore swell forecasts.
 39 | 
 40 | **Endpoint Format:**  
 41 | `https://api.spitcast.com/api/buoy_ww3/{county_id}/{year}/{month}/{day}`
 42 | 
 43 | **Example:**  
 44 | `https://api.spitcast.com/api/buoy_ww3/1/2025/3/14`
 45 | 
 46 | [About WAVEWATCH III](https://polar.ncep.noaa.gov/waves/wavewatch/)
 47 | 
 48 | ---
 49 | 
 50 | ### 💨 Wind Forecast
 51 | 
 52 | Wind forecast data sourced from NOAA’s National Digital Forecast Database.
 53 | 
 54 | **Endpoint Format:**  
 55 | `https://api.spitcast.com/api/buoy_ndfd/{county_id}/{year}/{month}/{day}`
 56 | 
 57 | **Example:**  
 58 | `https://api.spitcast.com/api/buoy_ndfd/1/2025/3/14`
 59 | 
 60 | [NDFD Info](https://graphical.weather.gov/)
 61 | 
 62 | ---
 63 | 
 64 | ### 🌊 Tide Forecast
 65 | 
 66 | Tide prediction data from NOAA's Tides & Currents.
 67 | 
 68 | **Endpoint Format:**  
 69 | `https://api.spitcast.com/api/buoy_tide/{county_id}/{year}/{month}/{day}`
 70 | 
 71 | **Example:**  
 72 | `https://api.spitcast.com/api/buoy_tide/1/2025/3/14`
 73 | 
 74 | [NOAA Tides & Currents](https://tidesandcurrents.noaa.gov/)
 75 | 
 76 | ---
 77 | 
 78 | ### 🌡️ Current Water Temperature
 79 | 
 80 | Water temperature data from NOAA's National Data Buoy Center.
 81 | 
 82 | **Endpoint Format:**  
 83 | `https://api.spitcast.com/api/buoy_ndbc/{county_id}/{year}/{month}/{day}`
 84 | 
 85 | **Example:**  
 86 | `https://api.spitcast.com/api/buoy_ndbc/1/2025/3/14`
 87 | 
 88 | [NDBC Info](https://www.ndbc.noaa.gov/)
 89 | 
 90 | ---
 91 | 
 92 | ## Terms of Use
 93 | 
 94 | 1. **Use at your own risk**  
 95 |    Uptime isn't guaranteed, and the API structure may change from time to time.
 96 | 
 97 | 2. **Forecasts aren’t perfect**  
 98 |    Surf forecasting is inherently uncertain. The model is under ongoing development to improve accuracy.
 99 | 
100 | 3. **Please give credit**  
101 |    If you're using Spitcast data publicly, a simple attribution is appreciated.
102 | 
103 | 4. **Don't use the Spitcast name**  
104 |    If you're building something public-facing (like an app), please don’t name it Spitcast. Use your own branding and mention it’s powered by Spitcast.
105 | 
106 | 5. **Share what you build**  
107 |    I’d love to see how you use this data. Feel free to reach out or share your projects!
108 | 


--------------------------------------------------------------------------------