Sunrise & Sunset Finder

A web application for finding accurate sunrise and sunset times for any location and date with timezone awareness, interactive map support, and responsive design. Built for both end users and developers with API access.

Key Features

Modern User Interface

• Interactive Map - Click anywhere to select coordinates
• Location Search - Geocode locations by name (e.g., Tokyo, Paris)
• Timezone Support - View sun times in both local time and UTC
• Theme Toggle - Switch between light and dark modes
• Responsive Design - Optimized for mobile and desktop

Developer API

• REST API Access - Get sunrise/sunset data via HTTP GET requests
• Rate Limiting - In-memory throttling to prevent abuse
• Development Tools - Includes /health and /docs endpoints for diagnostics

Technical Stack

• Frontend: HTML, CSS, Bootstrap 5, Leaflet.js, FontAwesome
• Backend: Flask, Astral, GeoPy, TimezoneFinder, Python
• External APIs:
  • Astral - Sun time calculations
  • OpenStreetMap + Nominatim - Geolocation services

Installation & Setup

Local Development

# Clone the repository
git clone https://github.com/RoyAalekh/suntimes.git
cd suntimes

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

Access the Application

• Web Interface: http://localhost:5000
• API Endpoint: http://localhost:5000/api/suntimes
• Health Check: http://localhost:5000/health
• Documentation: http://localhost:5000/docs

API Usage

Get Sunrise/Sunset Times

# By coordinates
curl "http://localhost:5000/api/suntimes?lat=40.7128&lng=-74.0060&date=2025-01-15"

# By location name
curl "http://localhost:5000/api/suntimes?location=New York&date=2025-01-15"

Response Format

{
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY, USA"
  },
  "date": "2025-01-15",
  "times": {
    "sunrise_utc": "12:20:15",
    "sunset_utc": "21:58:43",
    "sunrise_local": "07:20:15",
    "sunset_local": "16:58:43"
  },
  "timezone": "America/New_York"
}

Features

Web Interface

• Interactive map for location selection
• Date picker for custom date selection
• Real-time calculation display
• Timezone-aware time formatting
• Responsive mobile design

API Features

• RESTful endpoint design
• Multiple input formats (coordinates, location names)
• Comprehensive error handling
• Rate limiting for API protection
• JSON response format

Development

Project Structure

suntimes/
├── main.py                 # Flask application entry point
├── requirements.txt        # Python dependencies
├── static/                 # CSS, JavaScript, and assets
├── templates/              # HTML templates
└── README.md              # Project documentation

Dependencies

• Flask - Web framework
• Astral - Astronomical calculations
• GeoPy - Geocoding services
• TimezoneFinder - Timezone detection
• Requests - HTTP client library

Deployment

The application can be deployed on various platforms:

• Render - Direct deployment from GitHub
• Heroku - With Procfile configuration
• Docker - Containerized deployment
• VPS - Traditional server deployment

Contributing

Contributions are welcome! Areas for improvement:

• Additional astronomical calculations (moon phases, etc.)
• Historical data visualization
• Location favorites/bookmarks
• Batch API processing
• Mobile app version

License

MIT License - see LICENSE file for details.

Acknowledgments

• Astral - Core astronomical calculations
• OpenStreetMap - Map data and tiles
• Leaflet.js - Interactive mapping library
• Nominatim - Geocoding services

---

Accurate sunrise and sunset times for any location, with developer-friendly API access.