SunTimes - Sunrise and Sunset Calculation

1.1.2 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'suntimes'
```
cause The `suntimes` package is not installed in your current Python environment.

fix Install the package using pip: `pip install suntimes`
```
TypeError: risewhere() missing 1 required positional argument: 'timezone'
```
cause You called `risewhere()` or `setwhere()` without providing a timezone object, which is required for these methods.

fix Provide a timezone object (e.g., from `pytz.timezone('Europe/Paris')`) as the second argument: `sun.risewhere(some_date, my_timezone)`.
```
NameError: name 'SunTimes' is not defined
```
cause The `SunTimes` class was not imported correctly.

fix Ensure you have `from suntimes import SunTimes` at the top of your script.

Warnings

gotcha 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.
Fix: Do not expect sub-minute precision. Truncate or round results to the minute if presenting to users.
gotcha 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.
Fix: Be aware of reduced accuracy when using coordinates with high latitudes (close to +/- 90 degrees).
deprecated 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.
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)`.

Install

pip install suntimes Install stable release

Imports

SunTimes
```
from suntimes import SunTimes
```
SunFiles
```
from suntimes import SunFiles
```
Used for generating and saving yearly timetables.
datetime
```
import datetime
```
Standard library for date/time objects.

Quickstart

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.

import datetime
from suntimes import SunTimes
import pytz # Required for specific timezone handling

# Define location (e.g., Paris, France)
longitude = 2.349902
latitude = 48.852968
altitude = 0 # meters, default is 0

# Create a SunTimes instance for the location
sun = SunTimes(longitude, latitude, altitude)

# Get today's sunrise and sunset in UTC
today = datetime.date.today()

utc_sunrise = sun.riseutc(today)
utc_sunset = sun.setutc(today)
print(f"Today (UTC): Sunrise at {utc_sunrise.strftime('%H:%M:%S')}, Sunset at {utc_sunset.strftime('%H:%M:%S')}")

# Get sunrise and sunset in a specific timezone
paris_tz = pytz.timezone('Europe/Paris')
local_sunrise = sun.risewhere(today, paris_tz)
local_sunset = sun.setwhere(today, paris_tz)
print(f"Today (Paris): Sunrise at {local_sunrise.strftime('%H:%M:%S')}, Sunset at {local_sunset.strftime('%H:%M:%S')}")

# Example for a date in the past
some_date = datetime.date(2023, 7, 15)
summer_sunrise = sun.risewhere(some_date, paris_tz)
summer_sunset = sun.setwhere(some_date, paris_tz)
print(f"On {some_date.isoformat()} (Paris): Sunrise at {summer_sunrise.strftime('%H:%M:%S')}, Sunset at {summer_sunset.strftime('%H:%M:%S')}")

# Handling Polar Day/Night (returns specific string for rise/set times if applicable)
polar_lat = 89.0 # Near North Pole
polar_sun = SunTimes(0, polar_lat)
polar_date = datetime.date(2023, 6, 21) # Summer solstice

polar_rise = polar_sun.riseutc(polar_date)
polar_set = polar_sun.setutc(polar_date)
print(f"On {polar_date.isoformat()} at {polar_lat}°N (UTC): Sunrise: {polar_rise}, Sunset: {polar_set}")

view raw JSON →