Weather App - overclim8

A clean, minimalist weather application with Node.js/Express backend, Redis caching, and WeatherAPI.com integration.

Features

• 🌤️ Real-time weather data from WeatherAPI.com
• 📍 Automatic location detection using browser geolocation
• ⚡ Redis caching with 15-minute TTL for improved performance
• 🎨 Clean, minimalist UI inspired by modern weather apps
• 📱 Responsive design for mobile and desktop
• 🔄 Metric/Imperial unit conversion
• 📊 Comprehensive weather stats (humidity, pressure, visibility, etc.)
• ⏰ 24-hour hourly forecast
• 🌅 Sunrise/sunset times

Prerequisites

• Node.js (v16 or higher)
• Redis server
• WeatherAPI.com API key (free tier available)

Installation

1. Clone or download the project files

2. Install dependencies

   npm install

3. Set up Redis

   Option A: Local Redis installation

   # Ubuntu/Debian
   sudo apt-get install redis-server
   sudo systemctl start redis-server
   
   # macOS with Homebrew
   brew install redis
   brew services start redis
   
   # Windows - Download from https://redis.io/download

   Option B: Docker

   docker run -d -p 6379:6379 --name weather-redis redis:alpine

   Option C: Cloud Redis (Redis Cloud, AWS ElastiCache, etc.)

4. Get WeatherAPI.com API Key

   • Go to WeatherAPI.com
   • Sign up for a free account
   • Get your API key from the dashboard

5. Configure environment variables

   cp .env.example .env

   Edit .env file:

   PORT=3000
   WEATHER_API_KEY=your_actual_api_key_here
   REDIS_HOST=localhost
   REDIS_PORT=6379
   # REDIS_PASSWORD=your_redis_password (if needed)
   

6. Place the HTML file

   mkdir public
   # Move the weather app HTML file to public/index.html

Running the Application

1. Start the server

   # Development mode with auto-restart
   npm run dev
   
   # Production mode
   npm start

2. Access the application

   • Open your browser and go to http://localhost:3000
   • The app will automatically request your location
   • Allow location access for best experience

API Endpoints

Weather Data

GET /api/weather?lat={latitude}&lon={longitude}

Parameters:

• lat: Latitude (-90 to 90)
• lon: Longitude (-180 to 180)

Response:

{
  "location": {
    "name": "New York",
    "region": "New York",
    "country": "United States of America",
    "localtime": "2025-06-24 14:30"
  },
  "current": {
    "temp_c": 27,
    "temp_f": 80.6,
    "condition": {
      "text": "Partly cloudy",
      "icon": "//cdn.weatherapi.com/weather/64x64/day/116.png",
      "code": 1003
    },
    "wind_kph": 8.6,
    "wind_mph": 5.3,
    "humidity": 85,
    "pressure_mb": 1010,
    "feelslike_c": 27,
    "vis_km": 10.0
  },
  "forecast": {
    "sunrise": "06:06",
    "sunset": "18:45",
    "hourly": [...]
  },
  "cached": false,
  "timestamp": "2025-06-24T14:30:00.000Z"
}

Health Check

GET /api/health

Cache Management

GET /api/cache/stats      # View cache statistics
DELETE /api/cache/clear   # Clear all cached weather data

Project Structure

weather-app/
├── server.js           # Main Express server
├── package.json        # Dependencies and scripts
├── .env.example        # Environment variables template
├── .env               # Your environment variables (create this)
├── public/
│   └── index.html     # Frontend HTML file
└── README.md          # This file

Configuration Options

Redis Configuration

# Basic Redis setup
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_password

# Or use connection URL
REDIS_URL=redis://user:password@host:port

Cache Settings

• TTL: 15 minutes (900 seconds)
• Key format: weather:{lat}:{lon} (coordinates rounded to 2 decimal places)
• Storage: JSON stringified weather data

Rate Limiting

• Window: 15 minutes
• Max requests: 100 per IP
• Scope: All /api/* endpoints

Development

Adding New Features

1. Backend changes: Modify server.js
2. Frontend changes: Edit public/index.html
3. Dependencies: Update package.json

Environment Variables

Variable	Description	Default
PORT	Server port	3000
WEATHER_API_KEY	WeatherAPI.com API key	Required
REDIS_HOST	Redis server host	localhost
REDIS_PORT	Redis server port	6379
REDIS_PASSWORD	Redis password	None
NODE_ENV	Environment mode	development

Testing the API

# Test weather endpoint
curl "http://localhost:3000/api/weather?lat=40.7128&lon=-74.0060"

# Check health
curl "http://localhost:3000/api/health"

# View cache stats
curl "http://localhost:3000/api/cache/stats"

Deployment

Production Considerations

1. Environment Variables: Set all required environment variables
2. Redis: Use a managed Redis service (Redis Cloud, AWS ElastiCache)
3. Process Management: Use PM2 or similar process manager
4. Reverse Proxy: Use Nginx or similar for production
5. HTTPS: Enable SSL/TLS certificates
6. Monitoring: Add logging and monitoring solutions

Example PM2 Configuration

{
  "name": "weather-app",
  "script": "server.js",
  "instances": "max",
  "env": {
    "NODE_ENV": "production",
    "PORT": 3000
  }
}

Troubleshooting

Common Issues

1. Redis Connection Error

   • Verify Redis is running: redis-cli ping
   • Check connection settings in .env

2. WeatherAPI.com Errors

   • Verify API key is correct
   • Check API quotas and limits
   • Ensure coordinates are valid

3. Location Access Denied

   • Browser must be accessed via HTTPS for geolocation (except localhost)
   • User must grant location permission

4. Cache Not Working

   • Check Redis connection
   • Verify Redis has sufficient memory
   • Check TTL settings

Logs

The application logs important events:

• Redis connection status
• Cache hits/misses
• API errors
• Server startup

License

MIT License - feel free to use this project for your own purposes.

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request