☀️ Balcony Sun Tracker

A smart API that analyzes sunlight exposure for balconies, windows, and outdoor spaces to predict optimal drying conditions by combining astronomical calculations with real-time weather forecasts.

🎯 What It Does

This application helps you determine the best time to dry clothes or utilize your balcony, window, or outdoor space by:

• Calculating when direct sunlight hits your space based on its orientation
• Integrating weather forecasts (temperature, humidity, wind, clouds, rain)
• Computing a "drying efficiency" score that tells you how effective drying will be
• Providing confidence ratings based on weather conditions

🔬 How It Works

1. Sun Position Calculation

The tracker uses the SunCalc library to compute the sun's position (azimuth and altitude) throughout the day:

• Azimuth: The sun's horizontal angle (0-360°)
• Altitude: The sun's height above the horizon

It samples sun positions every 5 minutes from 5:00 AM to 7:00 PM.

2. Space Orientation Matching

Your space (balcony, window, etc.) has two key parameters:

• Heading: The direction your space faces (0-360°, where 0° = North, 90° = East, 180° = South, 270° = West)
• Tilt: Minimum sun altitude needed to reach your space (accounts for obstacles like buildings)
• View Angle: The arc of sky visible from your space (default: 90°)

The tracker only counts sunlight when:

• The sun's azimuth is within your space's view angle
• The sun's altitude is above the tilt threshold

3. Solar Strength Calculation

For each valid sun position, the solar strength is calculated as:

solarStrength = sunAltitude / 90

This means:

• Sun directly overhead (90°) = 100% strength
• Sun at 45° = 50% strength
• Lower sun = proportionally weaker

4. Weather Integration

The API fetches a 5-day forecast from OpenWeatherMap and extracts data for your sunlight window. It calculates:

• Average Temperature (°C)
• Average Humidity (%)
• Average Wind Speed (m/s)
• Average Cloud Cover (%)
• Rain Probability (%)

5. Drying Efficiency Score

The final drying efficiency is computed by applying weather factors to the solar strength:

efficiency = solarStrength × tempFactor × humidityFactor × windFactor × cloudFactor × rainFactor

Weather Factors:

• Temperature Factor: (temp - 10) / 20 (clamped 0.3-1.0)
  • Warmer = better drying (20°C+ is optimal)
• Humidity Factor: 1 - (humidity / 100)
  • Lower humidity = faster drying
• Wind Factor: windSpeed / 5 (clamped 0.3-1.0)
  • More wind = faster drying
• Cloud Factor: 1 - (clouds / 100)
  • Less cloud cover = stronger sun
• Rain Factor: 1 - (rainProb / 100)
  • Lower rain chance = better

The score is then averaged across all sun samples and converted to a percentage (0-100%).

6. Confidence Rating

• HIGH: Efficiency > 70% and sun window > 2 hours
• LOW: Efficiency < 30% or rain probability > 60%
• MEDIUM: Everything in between

📡 API Usage

Endpoint: POST /sun-analytics

Request Body:

{
  "lat": 40.7128,
  "lng": -74.0060,
  "date": "2026-01-20",
  "heading": 180,
  "tilt": 15
}

Parameters:

• lat (number): Latitude of your location
• lng (number): Longitude of your location
• date (string): Date in YYYY-MM-DD format
• heading (number): Direction your balcony faces in degrees (0-360)
• tilt (number): Minimum sun altitude needed (0-90)

Response:

{
  "date": "2026-01-20",
  "sunlightWindow": {
    "start": "09:30",
    "end": "14:45",
    "durationMinutes": 315
  },
  "peakSunTime": "12:15",
  "dryingEfficiency": 78,
  "confidence": "HIGH",
  "weatherSummary": {
    "averageTemperatureC": 22.5,
    "averageHumidityPercent": 45,
    "averageWindSpeed": 3.2,
    "averageCloudCoverPercent": 20,
    "averageRainProbabilityPercent": 5,
    "note": "Weather looks favorable"
  }
}

🚀 Getting Started

Prerequisites

• Node.js (v14 or higher)
• OpenWeatherMap API key (Get one free here)

Installation

1. Clone the repository

git clone <repository-url>
cd balcony_sun_tracker

2. Install dependencies

npm install

3. Create a .env file

PORT=3000
WEATHER_API_KEY=your_openweathermap_api_key_here
VIEW_ANGLE=90
WEATHER_TIMEOUT_MS=3000
CACHE_TTL_MS=1200000

4. Run the server

# Development mode (with auto-reload)
npm run dev

# Production mode
npm start

The server will start on http://localhost:3000

⚙️ Configuration

Variable	Default	Description
PORT	3000	Server port
VIEW_ANGLE	90	Visible arc of sky from your space (degrees)
WEATHER_API_KEY	-	OpenWeatherMap API key (required)
WEATHER_TIMEOUT_MS	3000	Weather API request timeout
CACHE_TTL_MS	1200000	Weather cache duration (20 min)

🧮 Example Use Cases

South-Facing Balcony in New York

{
  "lat": 40.7128,
  "lng": -74.0060,
  "date": "2026-06-21",
  "heading": 180,
  "tilt": 10
}

Expect long sunlight hours in summer with high drying efficiency.

East-Facing Window in London

{
  "lat": 51.5074,
  "lng": -0.1278,
  "date": "2026-01-20",
  "heading": 90,
  "tilt": 20
}

Morning sun only; efficiency may be lower due to winter conditions.

West-Facing Patio in California

{
  "lat": 34.0522,
  "lng": -118.2437,
  "date": "2026-07-15",
  "heading": 270,
  "tilt": 5
}

Afternoon and evening sun; great for late-day drying.

🛠️ Technical Stack

• Express.js: Web framework
• SunCalc: Astronomical calculations for sun position
• OpenWeatherMap API: Weather forecasting
• CORS: Cross-origin resource sharing support
• dotenv: Environment variable management

📊 Performance Features

• Weather Caching: Forecast data is cached for 20 minutes to reduce API calls
• Parallel Processing: Weather fetch happens in parallel with sun calculations
• Timeout Protection: Weather requests timeout after 3 seconds to prevent hanging

🌍 Real-World Factors Considered

✅ Included:

• Sun position (azimuth & altitude)
• Space orientation & view angle
• Temperature, humidity, wind
• Cloud cover & rain probability
• Building/obstacle shadows (via tilt parameter)

❌ Not Included:

• Local micro-climate variations
• Nearby building reflections
• Air quality/pollution
• Material-specific drying rates

📝 License

ISC

🤝 Contributing

Feel free to submit issues or pull requests to improve the algorithm or add new features!

📧 Contact

For any issues, questions, or feedback, feel free to reach out:

Email: tanvir.rrrabin@gmail.com

---

⭐ Star this repo if you find it helpful!

Made with ☀️ for optimal outdoor space utilization