astral
Module¶The astral
module provides the means to calculate dawn, sunrise,
solar noon, sunset, dusk and rahukaalam times, plus solar azimuth and
elevation, for specific locations or at a specific latitude/longitude. It can
also calculate the moon phase for a specific date.
The module provides 2 main classes Astral
and Location
.
Astral
Has 2 main responsibilities
Location
For example
>>> from astral import *
>>> a = Astral()
>>> location = a['London']
>>> print('Information for %s' % location.name)
Information for London
>>> timezone = location.timezone
>>> print('Timezone: %s' % timezone)
Timezone: Europe/London
>>> print('Latitude: %.02f; Longitude: %.02f' % (location.latitude,
... location.longitude))
Latitude: 51.60; Longitude: 0.05
>>> from datetime import date
>>> d = date(2009,4,22)
>>> sun = location.sun(local=True, date=d)
>>> print('Dawn: %s' % str(sun['dawn']))
Dawn: 20090422 05:12:56+01:00
The module currently provides 2 methods of obtaining location information;
AstralGeocoder
(the default, which uses information from within the
module) and GoogleGeocoder
(which obtains information from Google’s
Map Service.)
To use the GoogleGeocoder
pass the class as the geocoder parameter
to Astral.__init__()
or by setting the geocoder property to an
instance of GoogleGeocoder
:
>>> from astral import GoogleGeocoder
>>> a = Astral(GoogleGeocoder)
or
>>> from astral import GoogleGeocoder
>>> a = Astral()
>>> a.geocoder = GoogleGeocoder()
astral.
Astral
(geocoder=<class 'astral.AstralGeocoder'>)¶__getitem__
(key)¶Returns the Location instance specified by key
.
solar_depression
¶The number of degrees the sun must be below the horizon for the dawn/dusk calculation.
Can either be set as a number of degrees below the horizon or as one of the following strings
String  Degrees 

civil  6.0 
nautical  12.0 
astronomical  18.0 
sun_utc
(date, latitude, longitude)¶Calculate all the info for the sun at once. All times are returned in the UTC timezone.
Parameters: 


Returns:  Dictionary with keys 
Return type: 
dawn_utc
(date, latitude, longitude, depression=0)¶Calculate dawn time in the UTC timezone.
Parameters: 


Returns:  The UTC date and time at which dawn occurs. 
Return type: 
sunrise_utc
(date, latitude, longitude)¶Calculate sunrise time in the UTC timezone.
Parameters: 


Returns:  The UTC date and time at which sunrise occurs. 
Return type: 
solar_noon_utc
(date, longitude)¶Calculate solar noon time in the UTC timezone.
Parameters: 


Returns:  The UTC date and time at which noon occurs. 
Return type: 
sunset_utc
(date, latitude, longitude)¶Calculate sunset time in the UTC timezone.
Parameters: 


Returns:  The UTC date and time at which sunset occurs. 
Return type: 
dusk_utc
(date, latitude, longitude, depression=0)¶Calculate dusk time in the UTC timezone.
Parameters: 


Returns:  The UTC date and time at which dusk occurs. 
Return type: 
solar_midnight_utc
(date, longitude)¶Calculate solar midnight time in the UTC timezone.
Note that this claculates the solar midgnight that is closest to 00:00:00 of the specified date i.e. it may return a time that is on the previous day.
Parameters: 


Returns:  The UTC date and time at which midnight occurs. 
Return type: 
daylight_utc
(date, latitude, longitude)¶Calculate daylight start and end times in the UTC timezone.
Parameters: 


Returns:  A tuple of the UTC date and time at which daylight starts and ends. 
Return type: 
night_utc
(date, latitude, longitude)¶Calculate night start and end times in the UTC timezone.
Night is calculated to be between astronomical dusk on the date specified and astronomical dawn of the next day.
Parameters: 


Returns:  A tuple of the UTC date and time at which night starts and ends. 
Return type: 
twilight_utc
(direction, date, latitude, longitude)¶Returns the start and end times of Twilight in the UTC timezone when the sun is traversing in the specified direction.
This method defines twilight as being between the time when the sun is at 6 degrees and sunrise/sunset.
Parameters: 


Returns:  A tuple of the UTC date and time at which twilight starts and ends. 
Return type: 
golden_hour_utc
(direction, date, latitude, longitude)¶Returns the start and end times of the Golden Hour in the UTC timezone when the sun is traversing in the specified direction.
This method uses the definition from PhotoPills i.e. the golden hour is when the sun is between 4 degrees below the horizon and 6 degrees above.
Parameters: 


Returns:  A tuple of the UTC date and time at which the Golden Hour starts and ends. 
Return type: 
blue_hour_utc
(direction, date, latitude, longitude)¶Returns the start and end times of the Blue Hour in the UTC timezone when the sun is traversing in the specified direction.
This method uses the definition from PhotoPills i.e. the blue hour is when the sun is between 6 and 4 degrees below the horizon.
Parameters: 


Returns:  A tuple of the UTC date and time at which the Blue Hour starts and ends. 
Return type: 
time_at_elevation_utc
(elevation, direction, date, latitude, longitude)¶Calculate the time in the UTC timezone when the sun is at the specified elevation on the specified date.
Note: This method uses positive elevations for those above the horizon.
Parameters: 


Returns:  The UTC date and time at which the sun is at the required elevation. 
Return type: 
solar_azimuth
(dateandtime, latitude, longitude)¶Calculate the azimuth angle of the sun.
Parameters:  

Returns:  The azimuth angle in degrees clockwise from North. 
Return type: 
If dateandtime is a naive Python datetime then it is assumed to be in the UTC timezone.
solar_elevation
(dateandtime, latitude, longitude)¶Calculate the elevation angle of the sun.
Parameters:  

Returns:  The elevation angle in degrees above the horizon. 
Return type: 
If dateandtime is a naive Python datetime then it is assumed to be in the UTC timezone.
solar_zenith
(dateandtime, latitude, longitude)¶Calculates the solar zenith angle.
Parameters:  

Returns:  The zenith angle in degrees from vertical. 
Return type: 
If dateandtime is a naive Python datetime then it is assumed to be in the UTC timezone.
moon_phase
(date)¶Calculates the phase of the moon on the specified date.
Parameters:  date (datetime.date ) – The date to calculate the phase for. 

Returns:  A number designating the phase

Return type:  int 
rahukaalam_utc
(date, latitude, longitude)¶Calculate ruhakaalam times in the UTC timezone.
Parameters: 


Returns:  Tuple containing the start and end times for Rahukaalam. 
Return type: 
astral.
Location
(info=None)¶Provides access to information for single location.
__init__
(info=None)¶Initializes the object with a tuple of information.
Parameters:  info – A tuple of information to fill in the location info. The tuple should contain items in the following order
See 

latitude
¶The location’s latitude
latitude
can be set either as a string or as a number
For strings they must be of the form
degrees°minutes’[NS] e.g. 51°31’N
For numbers, positive numbers signify latitudes to the North.
longitude
¶The location’s longitude.
longitude
can be set either as a string or as a number
For strings they must be of the form
degrees°minutes’[EW] e.g. 51°31’W
For numbers, positive numbers signify longitudes to the East.
elevation
¶The elevation in metres above sea level.
timezone
¶The name of the time zone for the location.
A list of time zone names can be obtained from pytz. For example.
>>> from pytz import all_timezones
>>> for timezone in all_timezones:
... print(timezone)
tz
¶Time zone information.
tzinfo
¶Time zone information.
solar_depression
¶The number of degrees the sun must be below the horizon for the dawn/dusk calculation.
Can either be set as a number of degrees below the horizon or as one of the following strings
String  Degrees 

civil  6.0 
nautical  12.0 
astronomical  18.0 
sun
(date=None, local=True)¶Returns dawn, sunrise, noon, sunset and dusk as a dictionary.
Parameters: 


Returns:  Dictionary with keys 
Return type: 
dawn
(date=None, local=True)¶Calculates the time in the morning when the sun is a certain number
of degrees below the horizon. By default this is 6 degrees but can be
changed by setting the Astral.solar_depression
property.
Parameters: 


Returns:  The date and time at which dawn occurs. 
Return type: 
sunrise
(date=None, local=True)¶Return sunrise time.
Calculates the time in the morning when the sun is a 0.833 degrees below the horizon. This is to account for refraction.
Parameters: 


Returns:  The date and time at which sunrise occurs. 
Return type: 
solar_noon
(date=None, local=True)¶Calculates the solar noon (the time when the sun is at its highest point.)
Parameters: 


Returns:  The date and time at which the solar noon occurs. 
Return type: 
sunset
(date=None, local=True)¶Calculates sunset time (the time in the evening when the sun is a 0.833 degrees below the horizon. This is to account for refraction.)
Parameters: 


Returns:  The date and time at which sunset occurs. 
Return type: 
dusk
(date=None, local=True)¶Calculates the dusk time (the time in the evening when the sun is a
certain number of degrees below the horizon. By default this is 6
degrees but can be changed by setting the
solar_depression
property.)
Parameters: 


Returns:  The date and time at which dusk occurs. 
Return type: 
daylight
(date=None, local=True)¶Calculates the daylight time (the time between sunrise and sunset)
Parameters: 


Returns:  A tuple containing the start and end times 
Return type: 
night
(date=None, local=True)¶Calculates the night time (the time between astronomical dusk and astronomical dawn of the next day)
Parameters: 


Returns:  A tuple containing the start and end times 
Return type: 
twilight
(direction=SUN_RISING, date=None, local=True)¶Returns the start and end times of Twilight in the UTC timezone when the sun is traversing in the specified direction.
This method defines twilight as being between the time when the sun is at 6 degrees and sunrise/sunset.
Parameters: 


Returns:  A tuple of the UTC date and time at which twilight starts and ends. 
Return type: 
golden_hour
(direction=SUN_RISING, date=None, local=True)¶Returns the start and end times of the Golden Hour when the sun is traversing in the specified direction.
This method uses the definition from PhotoPills i.e. the golden hour is when the sun is between 4 degrees below the horizon and 6 degrees above.
Parameters: 


Returns:  A tuple of the date and time at which the Golden Hour starts and ends. 
Return type: 
blue_hour
(direction=SUN_RISING, date=None, local=True)¶Returns the start and end times of the Blue Hour when the sun is traversing in the specified direction.
This method uses the definition from PhotoPills i.e. the blue hour is when the sun is between 6 and 4 degrees below the horizon.
Parameters: 


Returns:  A tuple of the date and time at which the Blue Hour starts and ends. 
Return type: 
time_at_elevation
(elevation, direction=SUN_RISING, date=None, local=True)¶Calculate the time when the sun is at the specified elevation.
This method uses positive elevations for those above the horizon.
Elevations greater than 90 degrees are converted to a setting sun i.e. an elevation of 110 will calculate a setting sun at 70 degrees.
Parameters: 


Returns:  The date and time at which dusk occurs. 
Return type: 
solar_azimuth
(dateandtime=None)¶Calculates the solar azimuth angle for a specific date/time.
Parameters:  dateandtime (datetime ) – The date and time for which to calculate the angle. 

Returns:  The azimuth angle in degrees clockwise from North. 
Return type:  float 
solar_elevation
(dateandtime=None)¶Calculates the solar elevation angle for a specific time.
Parameters:  dateandtime (datetime ) – The date and time for which to calculate the angle. 

Returns:  The elevation angle in degrees above the horizon. 
Return type:  float 
solar_zenith
(dateandtime=None)¶Calculates the solar zenith angle for a specific time.
Parameters:  dateandtime (datetime ) – The date and time for which to calculate the angle. 

Returns:  The zenith angle in degrees from vertical. 
Return type:  float 
moon_phase
(date=None)¶Calculates the moon phase for a specific date.
Parameters:  date (datetime.date ) – The date to calculate the phase for.
If ommitted the current date is used. 

Returns:  A number designating the phase

Return type:  int 
rahukaalam
(date=None, local=True)¶Calculates the period of rahukaalam.
Parameters: 


Returns:  Tuple containing the start and end times for Rahukaalam. 
Return type: 
astral.
AstralGeocoder
¶Looks up geographic information from the locations stored within the module
astral.
GoogleGeocoder
(cache=False)¶Use Google Maps API Web Service to lookup GPS coordinates, timezone and elevation.
See the following for more info. https://developers.google.com/maps/documentation/