A web-based recreation of the classic Weatherscan IntelliStar cable TV weather display, powered by free, publicly accessible APIs.
The original Weatherscan project relied on the proprietary weather.com API, which requires special access arrangements. This fork replaces all weather.com API calls with free alternatives:
| Data Type | Original API | Replacement | Cost |
|---|---|---|---|
| Weather Data | weather.com | OpenWeatherMap | Free (1,000 calls/day) |
| Radar Tiles | weather.com | RainViewer | Free (unlimited) |
| Satellite | weather.com | RainViewer | Free (unlimited) |
| Map Tiles | Mapbox | Mapbox | Free (50,000 loads/month) |
How it works: A compatibility bridge (weather-bridge.js) intercepts all legacy weather.com API calls and transparently routes them through the new adapters. The original application code works without modification.
You'll need two free API keys before starting:
-
OpenWeatherMap API Key (required)
- Sign up at https://openweathermap.org/api
- Free tier: 1,000 API calls/day
- Note: Keys take ~10 minutes to activate after creation
-
Mapbox API Key (required)
- Sign up at https://www.mapbox.com/
- Free tier: 50,000 map loads/month
- Copy your "Default public token" from the dashboard
# Clone the repository
git clone https://github.com/negative-video/Weatherscan.git
cd Weatherscan
# Create your environment file
cp .env.example .env
# Edit .env and add your API keys
nano .envAdd your keys to .env:
OPENWEATHER_API_KEY=your_openweathermap_key_here
MAPBOX_API_KEY=your_mapbox_key_hereStart the application:
docker compose up -d
# View logs to verify startup
docker compose logs -fOpen http://localhost:8080 in your browser.
# Clone and install
git clone https://github.com/negative-video/Weatherscan.git
cd Weatherscan
npm install
# Configure API keys in config.js
nano webroot/js/config.jsSet your keys at the top of config.js:
var api_key = 'your_openweathermap_key_here';
var map_key = 'your_mapbox_key_here';Start the application:
npm startOpen http://localhost:8080 in your browser.
http://localhost:8080/?Philadelphia
http://localhost:8080/?New York, NY
http://localhost:8080/?90210
http://localhost:8080/?London, UK
Edit webroot/js/config.js and modify the locationSettings object:
var locationSettings = {
mainLocation: {
displayName: "Philadelphia",
searchQuery: {
type: "city",
val: "Philadelphia",
country: "US",
state: "PA"
}
}
};Once running, Weatherscan displays a continuous loop of weather information:
- Current Conditions - Temperature, humidity, wind, pressure, visibility
- Local Radar - Animated weather radar from RainViewer
- Hourly Forecast - Next 48 hours
- 5-Day Forecast - Extended outlook
- Weather Alerts - Active watches and warnings for your area
- Nearby Cities - Conditions in surrounding areas
The display cycles automatically, just like the original Weatherscan channel.
Check the browser console (F12) for startup messages:
╔══════════════════════════════════════════════════════════════╗
║ Weatherscan API Configuration Loaded ║
╚══════════════════════════════════════════════════════════════╝
Weather API: OpenWeatherMap (One Call 3.0)
Radar/Satellite: RainViewer (free, no key required)
CORS Proxy: http://localhost:8081/
✓ OpenWeatherMap adapter initialized
✓ RainViewer adapter initialized
If you see configuration errors, double-check your API keys.
- Verify your keys are set in
.env(Docker) orconfig.js(local) - OpenWeatherMap keys take ~10 minutes to activate after creation
- Check for typos or extra whitespace in your keys
- Open browser DevTools (F12) and check the Console and Network tabs
- Ensure the CORS proxy is running on port 8081
- Test your OpenWeatherMap key directly:
curl "https://api.openweathermap.org/data/3.0/onecall?lat=40&lon=-75&appid=YOUR_KEY"
- RainViewer doesn't require an API key - check browser Network tab for tile errors
- Verify your location has radar coverage (RainViewer primarily covers populated areas)
# Check if ports are in use
lsof -i :8080
lsof -i :8081
# Rebuild from scratch
docker compose down
docker compose up --build# Required
OPENWEATHER_API_KEY=your_key
MAPBOX_API_KEY=your_key
# Server ports (change if conflicts exist)
HTTP_PORT=8080
CORS_PORT=8081
# Caching (increase to reduce API calls)
CACHE_TTL_MINUTES=10
# Optional features
ENABLE_RADAR=true
ENABLE_SATELLITE=truevar apperanceSettings = {
iconSet: "2010", // Weather icon style: "2007" or "2010"
affilateName: "Your Cable", // Cable provider name shown on screen
corebackgroud: "buildings", // Background: forest, mountain, city, etc.
logoURL: "", // Custom logo URL (879x184px)
};
var audioSettings = {
enableMusic: true, // Background music
enableNarrations: true, // Voice announcements
narrationType: 'female', // 'female' or 'allen'
};Browser → CORS Proxy (8081) → Free APIs
↓
weather-bridge.js (intercepts $.getJSON calls)
↓
OpenWeatherMap / RainViewer adapters
↓
Transform to weather.com format
↓
Existing UI code (unchanged)
The bridge transforms OpenWeatherMap responses to match the weather.com format:
// OpenWeatherMap response
{ temp: 72.5, humidity: 65, weather: [{id: 801}] }
// Transformed to weather.com format
{ temperature: 73, relativeHumidity: 65, iconCode: 30 }This allows the original Weatherscan code to work without modification.
- SETUP_GUIDE.md - Detailed setup instructions including Docker and Dockge deployment
- API_MIGRATION_ANALYSIS.md - Technical details of the API replacement
- IMPLEMENTATION_SUMMARY.md - Overview of changes made
With the default 10-minute cache:
- ~400-800 API calls/day (well within free tier limits)
- Weather refreshes every 10 minutes
- Radar refreshes every 5 minutes
- Sustainable for 24/7 operation
- Original Weatherscan project by Jessecar96
- Weather data: OpenWeatherMap
- Radar/Satellite: RainViewer
- Maps: Mapbox
MIT License - See LICENSE file for details.
- Discord: https://discord.gg/WeatherRanch
- Issues: GitHub Issues