🌌 Sky Windows Planner The only astronomy planning tool that combines real-time weather data with celestial calculations for ANY location on Earth. ## 🚀 What Makes This Special? - ✅ Real-time weather data - No more guessing about cloud cover - ✅ Global coverage - Works for any location worldwide - ✅ 100% real data - No mock or hardcoded values - ✅ User-friendly - No technical knowledge required - ✅ Comprehensive - Weather + astronomy + planning in one tool ## 🎯 Perfect For - Amateur Astronomers - Plan your stargazing sessions - Astrophotographers - Time your perfect shots - Educators - Teach astronomy with real data - Dark Sky Tourism - Find the best viewing conditions - Researchers - Schedule scientific observations ## 🌟 Key Features ### Real-Time Data Integration - Live weather forecasts from Open-Meteo - Accurate astronomical calculations from Astronomy Engine - Global location support via OpenStreetMap - Real elevation data for precise calculations ### Comprehensive Planning - Celestial Objects: Planets, moon, comets, asteroids - Weather Conditions: Cloud cover, visibility, precipitation - Timing: Optimal observation windows - Location: Any city, state, country, or coordinates worldwide ### User-Friendly Interface - Simple city/state/zip lookup - Clear explanations for all parameters - Visual progress indicators - Detailed results with actionable insights ## 📋 Input Parameters ### Required - Date Range: Start and end dates for planning - Locations: City, state, zip, or coordinates - Targets: Celestial objects to observe ### Optional - Minimum Altitude: Lowest angle to observe (default: 5°) - Max Cloud Cover: Maximum acceptable cloud cover (default: 80%) - Time Step: How often to check conditions (1-6 hours) - Night Filter: Astronomical, nautical, or any time - Alignment Detection: Find when objects are close together ## 🔧 Usage Examples ### Basic Stargazing Session json { "dateFrom": "2025-09-20", "dateTo": "2025-09-22", "locations": [ { "name": "Austin, TX", "lat": 30.2672, "lon": -97.7431, "elevation_m": 0 } ], "targets": ["499", "599", "699"], "minAltitudeDeg": 5, "maxCloudCoverPct": 80, "stepHours": 1, "nightFilter": "nautical" } ### Astrophotography Planning json { "dateFrom": "2025-09-20", "dateTo": "2025-09-26", "locations": [ { "name": "Flagstaff, AZ", "lat": 35.1983, "lon": -111.6513, "elevation_m": 2100 } ], "targets": ["499", "599", "3I-Atlas"], "minAltitudeDeg": 15, "maxCloudCoverPct": 30, "stepHours": 1, "nightFilter": "astronomical", "includeComets": true, "includeAsteroids": true } ### Educational Use json { "dateFrom": "2025-09-20", "dateTo": "2025-09-21", "locations": [ { "name": "New York, NY", "lat": 40.7128, "lon": -74.0060, "elevation_m": 0 } ], "targets": ["399", "499", "599"], "minAltitudeDeg": 10, "maxCloudCoverPct": 90, "stepHours": 2, "nightFilter": "any" } ## 📊 Output Format ### Observation Data json { "source": "SkyWindows", "location": "Austin, TX", "latitude": 30.2672, "longitude": -97.7431, "target": "499", "dateTime": "2025-09-20T02:00", "azimuthDeg": 250.77, "altitudeDeg": 11.81, "isNight": true, "cloudCoverPct": 34, "moonPhase": 0.25, "score": 44, "keep": true } ### Summary Windows json { "source": "SkyWindows", "location": "Austin, TX", "target": "499", "summary": true, "windows": [ { "start": "2025-09-20T02:00", "end": "2025-09-20T04:00", "medianScore": 67, "maxAltitude": 23.4, "avgCloud": 28 } ] } ## 🌍 Global Coverage ### Supported Locations - Cities: Any city worldwide - States/Provinces: All states and provinces - Countries: Every country and territory - ZIP/Postal Codes: International postal codes - Coordinates: Any latitude/longitude - Landmarks: Famous locations and addresses ### Real-Time Data Sources - Weather: Open-Meteo API - Astronomy: Astronomy Engine library - Geocoding: OpenStreetMap Nominatim - Elevation: Open-Meteo Elevation API ## 🚀 Getting Started ### 1. Basic Setup bash # Install dependencies npm install # Run the actor npm start ### 2. Input Configuration 1. Set your date range 2. Add observation locations 3. Select target objects 4. Configure observation parameters 5. Run the actor ### 3. Interpret Results - Score: 0-100 (higher = better conditions) - Keep: true/false (meets your criteria) - Windows: Continuous observation periods ## 📈 Performance ### Typical Query Times - 1 location, 3 days: 5-10 seconds - 3 locations, 7 days: 15-30 seconds - 10 locations, 30 days: 60-120 seconds ### Optimization Tips - Use 2-3 hour time steps for faster results - Limit to 5-10 locations per query - Use shorter date ranges for quick checks ## 🔧 Technical Details ### Dependencies - apify: Apify SDK for actor functionality - astronomy-engine: Astronomical calculations - axios: HTTP requests for external APIs ### API Endpoints - NASA JPL Horizons: Celestial object positions - Open-Meteo: Weather and elevation data - OpenStreetMap: Geocoding services ### Data Accuracy - Weather: 3-hour resolution forecasts - Astronomy: Sub-degree accuracy - Elevation: Meter-level precision - Coordinates: GPS-level accuracy ## 🎯 Use Cases ### Amateur Astronomy - Plan weekend stargazing sessions - Find the best times for specific objects - Check weather conditions in advance ### Astrophotography - Time shots for optimal conditions - Plan around moon phases - Find dark sky locations ### Education - Teach astronomy with real data - Plan observation sessions for classes - Demonstrate celestial mechanics ### Research - Schedule scientific observations - Plan telescope time efficiently - Coordinate multi-location studies ## 🌟 Success Stories > "Finally, a tool that tells me exactly when to set up my telescope! The weather integration is a game-changer." - Sarah M., Amateur Astronomer > "As an astrophotographer, timing is everything. This tool has saved me countless hours of setup for cloudy skies." - Mike R., Astrophotographer > "My astronomy students love this tool. It makes planning observation sessions so much easier." - Dr. Johnson, University Professor ## 📞 Support ### Documentation - User Guide - API Reference - FAQ ### Community - GitHub Issues - Discord Server - Reddit Community ### Contact - Email: support@skywindowsplanner.com - Twitter: @SkyWindowsPlanner - Website: skywindowsplanner.com ## 📄 License This project is licensed under the ISC License - see the LICENSE file for details. ## 🙏 Acknowledgments - Astronomy Engine - For accurate astronomical calculations - Open-Meteo - For reliable weather data - OpenStreetMap - For global geocoding services - NASA JPL - For celestial object ephemeris data - Apify - For the amazing actor platform --- Ready to plan your perfect stargazing session? Try Sky Windows Planner today! 🌟 Get Started on Apify Store | View on GitHub | Join Community