{"id":9346,"library":"suntimes","title":"SunTimes - Sunrise and Sunset Calculation","description":"The `suntimes` library (version 1.1.2) provides functions to calculate sunrise and sunset times for a given geographical location (longitude, latitude, altitude) and day. It returns times in UTC and local time, handles polar day/night scenarios, and can generate yearly timetables in JSON or CSV format. It is actively maintained and has a steady release cadence for minor updates.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/p-mathis/suntimes","tags":["astronomy","time","date","sunrise","sunset","geography","location","datetime"],"install":[{"cmd":"pip install suntimes","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required for timezone handling.","package":"pytz","optional":false},{"reason":"Required for determining local timezone.","package":"tzlocal","optional":false},{"reason":"Used for Julian date calculations.","package":"jdcal","optional":false}],"imports":[{"symbol":"SunTimes","correct":"from suntimes import SunTimes"},{"note":"Used for generating and saving yearly timetables.","symbol":"SunFiles","correct":"from suntimes import SunFiles"},{"note":"Standard library for date/time objects.","symbol":"datetime","correct":"import datetime"}],"quickstart":{"code":"import datetime\nfrom suntimes import SunTimes\nimport pytz # Required for specific timezone handling\n\n# Define location (e.g., Paris, France)\nlongitude = 2.349902\nlatitude = 48.852968\naltitude = 0 # meters, default is 0\n\n# Create a SunTimes instance for the location\nsun = SunTimes(longitude, latitude, altitude)\n\n# Get today's sunrise and sunset in UTC\ntoday = datetime.date.today()\n\nutc_sunrise = sun.riseutc(today)\nutc_sunset = sun.setutc(today)\nprint(f\"Today (UTC): Sunrise at {utc_sunrise.strftime('%H:%M:%S')}, Sunset at {utc_sunset.strftime('%H:%M:%S')}\")\n\n# Get sunrise and sunset in a specific timezone\nparis_tz = pytz.timezone('Europe/Paris')\nlocal_sunrise = sun.risewhere(today, paris_tz)\nlocal_sunset = sun.setwhere(today, paris_tz)\nprint(f\"Today (Paris): Sunrise at {local_sunrise.strftime('%H:%M:%S')}, Sunset at {local_sunset.strftime('%H:%M:%S')}\")\n\n# Example for a date in the past\nsome_date = datetime.date(2023, 7, 15)\nsummer_sunrise = sun.risewhere(some_date, paris_tz)\nsummer_sunset = sun.setwhere(some_date, paris_tz)\nprint(f\"On {some_date.isoformat()} (Paris): Sunrise at {summer_sunrise.strftime('%H:%M:%S')}, Sunset at {summer_sunset.strftime('%H:%M:%S')}\")\n\n# Handling Polar Day/Night (returns specific string for rise/set times if applicable)\npolar_lat = 89.0 # Near North Pole\npolar_sun = SunTimes(0, polar_lat)\npolar_date = datetime.date(2023, 6, 21) # Summer solstice\n\npolar_rise = polar_sun.riseutc(polar_date)\npolar_set = polar_sun.setutc(polar_date)\nprint(f\"On {polar_date.isoformat()} at {polar_lat}°N (UTC): Sunrise: {polar_rise}, Sunset: {polar_set}\")","lang":"python","description":"This quickstart demonstrates how to initialize the `SunTimes` object with geographical coordinates and retrieve sunrise and sunset times for a given date in UTC and a specified local timezone using `pytz`. It also includes an example of handling dates near the poles where 'Polar Day' or 'Polar Night' strings are returned."},"warnings":[{"fix":"Do not expect sub-minute precision. Truncate or round results to the minute if presenting to users.","message":"The library's calculations have a precision of 'one to several minutes'. Results are not guaranteed to be accurate to the second and should not be relied upon for high-precision applications requiring sub-minute accuracy.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of reduced accuracy when using coordinates with high latitudes (close to +/- 90 degrees).","message":"Accuracy decreases significantly closer to the Earth's poles. While the library handles polar day/night scenarios by returning specific strings, the numerical results for times close to these periods may have lower accuracy.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use 'sun.risewhere(date, timezone)' and 'sun.setwhere(date, timezone)' for local times with `p-mathis/suntimes` for clarity and correctness. For UTC, use `sun.riseutc(date)` and `sun.setutc(date)`.","message":"Older versions of a *different* 'suntime' library (not 'suntimes' by p-mathis) had deprecated methods like 'get_local_sunrise_time()' and 'get_local_sunset_time()'. While not directly applicable to 'p-mathis/suntimes', ensure you are using the 'risewhere()' and 'setwhere()' methods with explicit timezone arguments for local times to avoid confusion.","severity":"deprecated","affected_versions":"N/A (relevant to related 'suntime' library)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install suntimes`","cause":"The `suntimes` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'suntimes'"},{"fix":"Provide a timezone object (e.g., from `pytz.timezone('Europe/Paris')`) as the second argument: `sun.risewhere(some_date, my_timezone)`.","cause":"You called `risewhere()` or `setwhere()` without providing a timezone object, which is required for these methods.","error":"TypeError: risewhere() missing 1 required positional argument: 'timezone'"},{"fix":"Ensure you have `from suntimes import SunTimes` at the top of your script.","cause":"The `SunTimes` class was not imported correctly.","error":"NameError: name 'SunTimes' is not defined"}]}