196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# Weather Feature Guide
|
|
|
|
## Overview
|
|
|
|
The weather feature has been fully implemented on the `/map` page, providing real-time weather data, air quality information, and skateability scoring for all skate spots.
|
|
|
|
## How to Use
|
|
|
|
### 1. View Weather on Map
|
|
|
|
#### Enable Weather Layer
|
|
|
|
1. Navigate to `/map` page
|
|
2. Look for the "Weather Off" button in the toolbar (next to Map/List toggle)
|
|
3. Click the button to enable weather - it will change to "Weather On" and turn blue
|
|
4. Wait a few seconds for weather data to load
|
|
|
|
#### View Weather-Colored Markers
|
|
|
|
Once enabled, you'll see:
|
|
- **Color-coded markers**: Spot markers change color based on skating conditions
|
|
- 🟢 Green = Perfect conditions (85-100 score)
|
|
- 🟡 Yellow = Good conditions (70-84 score)
|
|
- 🟠 Orange = Okay conditions (50-69 score)
|
|
- 🔴 Red = Poor/bad conditions (0-49 score)
|
|
- **Weather icons**: Small weather emoji appears on each marker (☀️, ⛅, 🌧️, etc.)
|
|
|
|
### 2. View Weather on Spot Detail Pages
|
|
|
|
Weather information is **automatically displayed** on every spot detail page (`/spot/:pubkey/:identifier`):
|
|
|
|
1. Click any spot on the map or navigate to a spot detail page
|
|
2. Look for the **Weather Conditions** card in the sidebar (blue gradient design)
|
|
3. View comprehensive weather information including:
|
|
- Current temperature and conditions
|
|
- Skateability score with color-coded indicator
|
|
- Wind speed and direction
|
|
- Humidity percentage
|
|
- UV index (sun protection guidance)
|
|
- Air quality index (if available)
|
|
- 3-day forecast with daily temps and precipitation
|
|
- Feels-like temperature
|
|
|
|
**No toggle required** - weather data loads automatically on all spot pages!
|
|
|
|
### 3. View Detailed Weather in Map Popups
|
|
|
|
Click any spot marker on the map to see a popup with:
|
|
- Current temperature (°F) and feels-like
|
|
- Weather conditions and icon
|
|
- Skateability score and label
|
|
- Wind speed and direction
|
|
- Humidity percentage
|
|
- Air quality index (if available)
|
|
- 3-day forecast with high/low temps
|
|
- Precipitation probability
|
|
|
|
### 4. Filter by Weather
|
|
|
|
When weather is enabled, three additional filter buttons appear:
|
|
- **All Weather** (blue): Show all spots regardless of weather
|
|
- **Good Weather (70+)** (yellow): Show only spots with good or better conditions
|
|
- **Perfect Weather (85+)** (green): Show only spots with perfect skating weather
|
|
|
|
## Where Weather Appears
|
|
|
|
Weather information is displayed in **three places**:
|
|
|
|
1. **Map View** (`/map` with weather toggle enabled):
|
|
- Color-coded spot markers
|
|
- Weather icons on markers
|
|
- Quick weather info in popups
|
|
|
|
2. **Spot Detail Pages** (`/spot/:pubkey/:identifier`):
|
|
- Full weather card in sidebar
|
|
- Comprehensive weather details
|
|
- 3-day forecast
|
|
- Always visible (no toggle needed)
|
|
|
|
3. **Map Popups** (when weather enabled):
|
|
- Current conditions summary
|
|
- Temperature and feels-like
|
|
- Skateability score
|
|
- 3-day forecast preview
|
|
|
|
## Features
|
|
|
|
### Weather Data Includes
|
|
- ✅ Temperature (°F and °C)
|
|
- ✅ Feels-like temperature
|
|
- ✅ Weather conditions (sunny, cloudy, rainy, etc.)
|
|
- ✅ Precipitation and probability
|
|
- ✅ Wind speed and direction
|
|
- ✅ Humidity
|
|
- ✅ UV index
|
|
- ✅ Air quality (AQI, PM2.5, PM10)
|
|
- ✅ 3-day forecast
|
|
|
|
### Skateability Scoring
|
|
|
|
The app calculates a 0-100 score based on:
|
|
- ❌ **Dealbreakers** (score = 0):
|
|
- Currently raining/snowing
|
|
- Thunderstorms
|
|
- Active precipitation
|
|
|
|
- **Score Penalties**:
|
|
- Freezing temps (<0°C): -50 points
|
|
- Very cold (<5°C): -30 points
|
|
- Extreme heat (>38°C): -40 points
|
|
- Very hot (>32°C): -20 points
|
|
- Strong wind (>25 km/h): -25 points
|
|
- Very humid (>90%): -15 points
|
|
- Poor air quality (AQI >150): -25 points
|
|
|
|
### API Details
|
|
|
|
- **Provider**: Open-Meteo (free, no API key required)
|
|
- **Coverage**: Worldwide
|
|
- **Cache**: 10 minutes stale time, 30 minutes garbage collection
|
|
- **Retry**: 2 automatic retries on failure
|
|
|
|
## Troubleshooting
|
|
|
|
If weather data isn't showing:
|
|
|
|
1. **Check Console Logs**:
|
|
- Open browser DevTools (F12)
|
|
- Look for logs starting with `[MapPage]` or `[useMultipleSpotWeather]`
|
|
- Check for geohash extraction: `[MapPage] Spot geohashes: [...]`
|
|
- Check for weather fetch: `[useMultipleSpotWeather] Fetching weather for geohashes: [...]`
|
|
|
|
2. **Verify Weather Toggle**:
|
|
- Button should change from "Weather Off" (gray) to "Weather On" (blue)
|
|
- State should be saved and persist across page refreshes
|
|
|
|
3. **Check Network Tab**:
|
|
- Look for requests to `api.open-meteo.com`
|
|
- Verify requests complete successfully (status 200)
|
|
|
|
4. **Verify Spot Data**:
|
|
- Spots must have valid geohash values
|
|
- Check console log: `[MapPage] Spot geohashes` should show array of geohashes
|
|
- If array is empty, spots don't have geohash data
|
|
|
|
5. **Browser Support**:
|
|
- Modern browsers (Chrome, Firefox, Safari, Edge)
|
|
- JavaScript enabled
|
|
- No ad blockers blocking Open-Meteo API
|
|
|
|
## Technical Implementation
|
|
|
|
### Files Created/Modified
|
|
|
|
**New Files**:
|
|
- `/src/lib/weather.ts` - Weather API service and skateability calculations
|
|
- `/src/hooks/useSpotWeather.ts` - React hooks for weather data
|
|
- `/src/components/WeatherToggle.tsx` - Weather toggle button component
|
|
- `/src/components/PWAInstallPrompt.tsx` - PWA install prompt (bonus feature)
|
|
|
|
**Modified Files**:
|
|
- `/src/pages/MapPage.tsx` - Added weather state and filtering
|
|
- `/src/components/SpotMap.tsx` - Added weather marker colors and popups
|
|
- `/src/pages/SpotDetailPage.tsx` - Added weather card to sidebar
|
|
|
|
### Key Components
|
|
|
|
1. **Weather Service** (`lib/weather.ts`):
|
|
- `fetchWeather()` - Get current weather for lat/lng
|
|
- `fetchAirQuality()` - Get air quality data
|
|
- `fetchWeatherForecast()` - Get 3-day forecast
|
|
- `calculateSkateability()` - Calculate 0-100 score
|
|
|
|
2. **React Hooks** (`hooks/useSpotWeather.ts`):
|
|
- `useSpotWeather()` - Single spot weather
|
|
- `useMultipleSpotWeather()` - Batch weather for all spots
|
|
|
|
3. **UI Components**:
|
|
- `WeatherToggle` - Toggle button with state
|
|
- `SpotMap` - Weather-colored markers and detailed popups
|
|
|
|
## Next Steps
|
|
|
|
Possible enhancements:
|
|
- Weather-based notifications ("Perfect skating weather at X spot!")
|
|
- Historical weather data
|
|
- Best time to skate recommendations
|
|
- Weather radar overlay
|
|
- Wind direction visualization
|
|
- Precipitation forecasts with timing
|
|
|
|
## Credits
|
|
|
|
- Weather data: [Open-Meteo](https://open-meteo.com/)
|
|
- Air quality data: Open-Meteo Air Quality API
|
|
- Map: OpenStreetMap
|