Main Sections

Python Subsections

Astral – Python Sun Calculations.

Astral is a Python module designed to calculate the following times of the day...

Plus solar azimuth and elevation, at a particular time...

for any latitude and longitude.

The following example shows how the module can be used.

from astral import Astral

city-name = 'London'

astral = Astral() = 'civil'

city = astral[city-name]

print('Information for %s/%s\n' % (city-name,

tz-name =
print('Timezone: %s' % tz-name)

print('Latitude: %.02f; Longitude: %.02f\n' % (city.latitude, city.longitude))

sun = city.sun(local=True)
print('Dawn:    %s' % str(sun['dawn']))
print('Sunrise: %s' % str(sun['sunrise']))
print('Noon:    %s' % str(sun['noon']))
print('Sunset:  %s' % str(sun['sunset']))
print('Dusk:    %s' % str(sun['dusk']))

Which produces the following output:

Information for London/England

Timezone: Europe/London
Latitude: 51.60; Longitude: 0.08

Dawn:     2009-04-22 05:12:56+01:00
Sunrise:  2009-04-22 05:49:36+01:00
Noon:     2009-04-22 12:58:48+01:00
Sunset:   2009-04-22 20:09:07+01:00
Dusk:     2009-04-22 20:45:52+01:00


Documentation can be found here.


Astral is dependent on the following Python libraries


Version Description URL
0.7.4 Added Canadian cities from Yip Shing Ho
0.7.3 Fix for bug 1239387 submitted by Torbjörn Lönnemark.
0.7.2 Minor bug fix in the GoogleGeocoder class. location name and region are now stripped of whitespace.
0.7.1 Bug fix. Missed a vital return statement in the GoogleGeocoder class.
  • Added capability to retrieve geo data from Google's mapping service
  • Renamed City class to Location
  • Renamed CityDB to AstralGeocoder
  • Added elevations of cities to database and property to obtain elevation from Location class
  • Corrected inconsistencies in docstrings
  • Fix for bug 884716 submitted by Martin Heemskerk regarding moon phase calculations
  • Fixes for bug report 944754 submitted by Hajo Werder
    • Changed co-ordinate system so that eastern longitudes are now positive
    • Added solar_depression property to City class
  • Changed City to accept unicode name and country.
  • Moved city information into a database class CityDB
  • Added attribute access to database for timezone groups
  • Duplicate city names could not be accessed.
  • Sun calculations for some cities failed with times outside valid ranges.
  • Fixes for city data.
  • Added calculation for moon phase.
  • Changed to Apache V2.0 license.
  • Fix for bug #555508 submitted by me.
  • US state capitals and other cities added.
0.2 Fix for bug #554041 (MIT license.)
0.1 Initial version (MIT license.)

Source Code

The source code for the Astral package can be browsed here

You can download the latest version of the source using Bazaar (bzr)

bzr checkout lp:astral

Bug Reports

Please use the Astral project page on to submit bug reports.