{"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":"python","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,"search_vec":"'1.1.2':10 'activ':53 'altitud':26 'astronomi':64 'cadenc':60 'calcul':5,14 'csv':49 'date':66 'datetim':71 'day':28 'day/night':39 'format':50 'function':12 'generat':43 'geograph':22 'geographi':69 'given':21 'handl':37 'json':47 'latitud':25 'librari':8 'local':35 'locat':23,70 'longitud':24 'maintain':54 'minor':62 'polar':38 'provid':11 'releas':59 'return':30 'scenario':40 'steadi':58 'sunris':2,15,67 'sunset':4,17,68 'suntim':1,7 'time':18,31,36,65 'timet':45 'updat':63 'utc':33 'version':9 'year':44","created_at":"2026-04-16T18:49:44.301084+00:00","updated_at":"2026-04-16T18:49:44.301084+00:00","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"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.1.2","cli_name":"suntimes","cli_version":"sh: 1: suntimes: not found","type":"library","homepage":null,"github":"https://github.com/p-mathis/suntimes","docs":null,"changelog":null,"pypi":"https://pypi.org/project/suntimes/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}