SkateSpots/WEATHER_FEATURE.md

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
• Air quality data: Open-Meteo Air Quality API
• Map: OpenStreetMap