This is a FastAPI-based Surf Forecast API that retrieves real-time surf conditions for different locations using the Stormglass API. The application supports location-based caching using SQLite to improve performance.
- Fetches wave height, wind speed, and water temperature for a given location and date.
- Geocoding support via OpenStreetMap to dynamically retrieve latitude/longitude.
- SQLite caching for both location coordinates and surf forecasts.
- Asynchronous support for improved performance.
- Auto-retries on failures and API error handling.
# Clone the repository
git clone https://github.com/yourusername/surf-forecast-api.git
cd surf-forecast-api
Ensure you have Python 3.9+ installed. Then, set up a virtual environment:
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # For macOS/Linux
venv\Scripts\activate # For Windows
# Install required dependencies
pip install --upgrade pip
pip install fastapi uvicorn requests aiosqlite geopy python-dotenv
You need a Stormglass API key. Sign up at Stormglass.io and get an API key.
Create a .env
file in the project root and add:
STORMGLASS_API_KEY=your_api_key_here
uvicorn app.main:app --reload
You can use cURL or Postman to test the API.
curl -X 'POST'
'http://127.0.0.1:8000/forecast' -H 'Content-Type: application/json' -d '{ "location": "Praia do Rosa, SC, Brazil", "date": "2025-03-10" }'
{
"location": "Praia do Rosa, SC, Brazil",
"date": "2025-03-10",
"latitude": -28.1260,
"longitude": -48.6436,
"wave_height": 2.5,
"wind_speed": 15,
"water_temperature": 24,
"meta": { "source": "noaa" }
}
- SQLite database (
locations_cache.db
) is used for caching. - Cached data includes:
- Coordinates (so we don’t re-query OpenStreetMap for the same location).
- Surf forecasts (to reduce external API calls).
- The cache persists between application restarts.
If you ever need to clear the cache, delete the database:
rm locations_cache.db
Fetches surf forecast data for a location.
{
"location": "Hawaii",
"date": "2025-03-10"
}
{
"location": "Hawaii",
"date": "2025-03-10",
"latitude": 21.3069,
"longitude": -157.8583,
"wave_height": 2.5,
"wind_speed": 10,
"water_temperature": 27,
"meta": { "source": "noaa" }
}
- 🔹 Add Redis caching to further optimize performance.
- 🔹 Implement automatic cache expiration.
- 🔹 Support more surf parameters (e.g., swell period, tide levels).
- 🔹 Improve location handling by integrating a full geolocation API.
This project is open-source under the MIT License.
Developed by Felipe Kautzmann 🚀