The astral Package

Calculations for the position of the sun and moon.

The astral package provides the means to calculate the following times of the sun

  • dawn
  • sunrise
  • noon
  • midnight
  • sunset
  • dusk
  • daylight
  • night
  • twilight
  • blue hour
  • golden hour
  • rahukaalam
  • moon rise, set, azimuth and zenith

plus solar azimuth and elevation at a specific latitude/longitude. It can also calculate the moon phase for a specific date.

The package also provides a self contained geocoder to turn a small set of location names into timezone, latitude and longitude. The lookups can be perfomed using the lookup() function defined in astral.geocoder

class astral.Depression

The depression angle in degrees for the dawn/dusk calculations

class astral.SunDirection

Direction of the sun either RISING or SETTING

class astral.Observer(latitude: float = 51.4733, longitude: float = -0.0008333, elevation: Union[float, Tuple[float, float]] = 0.0)

Defines the location of an observer on Earth.

Latitude and longitude can be set either as a float or as a string. For strings they must be of the form

degrees°minutes’seconds”[N|S|E|W] e.g. 51°31’N

minutes’ & seconds” are optional.

Elevations are either

  • A float that is the elevation in metres above a location, if the nearest obscuring feature is the horizon
  • or a tuple of the elevation in metres and the distance in metres to the nearest obscuring feature.
Parameters:
  • latitude – Latitude - Northern latitudes should be positive
  • longitude – Longitude - Eastern longitudes should be positive
  • elevation – Elevation and/or distance to nearest obscuring feature in metres above/below the location.
class astral.LocationInfo(name: str = 'Greenwich', region: str = 'England', timezone: str = 'Europe/London', latitude: float = 51.4733, longitude: float = -0.0008333)

Defines a location on Earth.

Latitude and longitude can be set either as a float or as a string. For strings they must be of the form

degrees°minutes’seconds”[N|S|E|W] e.g. 51°31’N

minutes’ & seconds” are optional.

Parameters:
  • name – Location name (can be any string)
  • region – Region location is in (can be any string)
  • timezone – The location’s time zone (a list of time zone names can be obtained from zoneinfo.available_timezones)
  • latitude – Latitude - Northern latitudes should be positive
  • longitude – Longitude - Eastern longitudes should be positive
observer

Return an Observer at this location

timezone_group

Return the group a timezone is in

tzinfo

Return a zoneinfo.ZoneInfo for this location

class astral.AstralBodyPosition(right_ascension: float = <factory>, declination: float = <factory>, distance: float = <factory>)

The position of an astral body as seen from earth

astral.now(tz: Optional[datetime.tzinfo] = None) → datetime.datetime

Returns the current time in the specified time zone

astral.today(tz: Optional[datetime.tzinfo] = None) → datetime.date

Returns the current date in the specified time zone

astral.dms_to_float(dms: Union[str, float, Tuple[float, float]], limit: Optional[float] = None) → float

Converts as string of the form degrees°minutes’seconds”[N|S|E|W], or a float encoded as a string, to a float

N and E return positive values S and W return negative values

Parameters:
  • dms – string to convert
  • limit – Limit the value between ± limit
Returns:

The number of degrees as a float

astral.refraction_at_zenith(zenith: float) → float

Calculate the degrees of refraction of the sun due to the sun’s elevation.

astral.sun

astral.sun.sun(observer: astral.Observer, date: Optional[datetime.date] = None, dawn_dusk_depression: Union[float, astral.Depression] = <Depression.CIVIL: 6>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Dict[str, datetime.datetime]

Calculate all the info for the sun at once.

Parameters:
  • observer – Observer for which to calculate the times of the sun
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • dawn_dusk_depression – Depression to use to calculate dawn and dusk. Default is for Civil dusk i.e. 6.0
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Dictionary with keys dawn, sunrise, noon, sunset and dusk whose values are the results of the corresponding functions.

Raises:

ValueError – if passed through from any of the functions

astral.sun.dawn(observer: astral.Observer, date: Optional[datetime.date] = None, depression: Union[float, astral.Depression] = <Depression.CIVIL: 6>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate dawn time.

Parameters:
  • observer – Observer to calculate dawn for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • depression – Number of degrees below the horizon to use to calculate dawn. Default is for Civil dawn i.e. 6.0
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which dawn occurs.

Raises:

ValueError – if dawn does not occur on the specified date

astral.sun.sunrise(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate sunrise time.

Parameters:
  • observer – Observer to calculate sunrise for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which sunrise occurs.

Raises:

ValueError – if the sun does not reach the horizon on the specified date

astral.sun.noon(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate solar noon time when the sun is at its highest point.

Parameters:
  • observer – An observer viewing the sun at a specific, latitude, longitude and elevation
  • date – Date to calculate for. Default is today for the specified tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which noon occurs.

astral.sun.midnight(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate solar midnight time.

Note

This calculates the solar midnight 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:
  • observer – An observer viewing the sun at a specific, latitude, longitude and elevation
  • date – Date to calculate for. Default is today for the specified tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which midnight occurs.

astral.sun.sunset(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate sunset time.

Parameters:
  • observer – Observer to calculate sunset for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which sunset occurs.

Raises:

ValueError – if the sun does not reach the horizon

astral.sun.dusk(observer: astral.Observer, date: Optional[datetime.date] = None, depression: Union[float, astral.Depression] = <Depression.CIVIL: 6>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → datetime.datetime

Calculate dusk time.

Parameters:
  • observer – Observer to calculate dusk for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • depression – Number of degrees below the horizon to use to calculate dusk. Default is for Civil dusk i.e. 6.0
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which dusk occurs.

Raises:

ValueError – if dusk does not occur on the specified date

astral.sun.daylight(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

Calculate daylight start and end times.

Parameters:
  • observer – Observer to calculate daylight for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

A tuple of the date and time at which daylight starts and ends.

Raises:

ValueError – if the sun does not rise or does not set

astral.sun.night(observer: astral.Observer, date: Optional[datetime.date] = None, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

Calculate night start and end times.

Night is calculated to be between astronomical dusk on the date specified and astronomical dawn of the next day.

Parameters:
  • observer – Observer to calculate night for
  • date – Date to calculate for. Default is today’s date for the specified tzinfo.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

A tuple of the date and time at which night starts and ends.

Raises:

ValueError – if dawn does not occur on the specified date or dusk on the following day

astral.sun.twilight(observer: astral.Observer, date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

Returns the start and end times of Twilight 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:
  • observer – Observer to calculate twilight for
  • date – Date for which to calculate the times. Default is today’s date in the timezone tzinfo.
  • direction – Determines whether the time is for the sun rising or setting. Use astral.SunDirection.RISING or astral.SunDirection.SETTING.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

A tuple of the date and time at which twilight starts and ends.

Raises:

ValueError – if the sun does not rise or does not set

astral.sun.blue_hour(observer: astral.Observer, date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

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:
  • observer – Observer to calculate the blue hour for
  • date – Date for which to calculate the times. Default is today’s date in the timezone tzinfo.
  • direction – Determines whether the time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

A tuple of the date and time at which the Blue Hour starts and ends.

Raises:

ValueError – if the sun does not transit the elevations -4 & -6 degrees

astral.sun.golden_hour(observer: astral.Observer, date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

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:
  • observer – Observer to calculate the golden hour for
  • date – Date for which to calculate the times. Default is today’s date in the timezone tzinfo.
  • direction – Determines whether the time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

A tuple of the date and time at which the Golden Hour starts and ends.

Raises:

ValueError – if the sun does not transit the elevations -4 & +6 degrees

astral.sun.rahukaalam(observer: astral.Observer, date: Optional[datetime.date] = None, daytime: bool = True, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc) → Tuple[datetime.datetime, datetime.datetime]

Calculate ruhakaalam times.

Parameters:
  • observer – Observer to calculate rahukaalam for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • daytime – If True calculate for the day time else calculate for the night time.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Tuple containing the start and end times for Rahukaalam.

Raises:

ValueError – if the sun does not rise or does not set

astral.sun.zenith(observer: astral.Observer, dateandtime: Optional[datetime.datetime] = None, with_refraction: bool = True) → float

Calculate the zenith angle of the sun.

Parameters:
  • observer – Observer to calculate the solar zenith for
  • dateandtime – The date and time for which to calculate the angle. If dateandtime is None or is a naive Python datetime then it is assumed to be in the UTC timezone.
  • with_refraction – If True adjust zenith to take refraction into account
Returns:

The zenith angle in degrees.

astral.sun.azimuth(observer: astral.Observer, dateandtime: Optional[datetime.datetime] = None) → float

Calculate the azimuth angle of the sun.

Parameters:
  • observer – Observer to calculate the solar azimuth for
  • dateandtime – The date and time for which to calculate the angle. If dateandtime is None or is a naive Python datetime then it is assumed to be in the UTC timezone.
Returns:

The azimuth angle in degrees clockwise from North.

If dateandtime is a naive Python datetime then it is assumed to be in the UTC timezone.

astral.sun.elevation(observer: astral.Observer, dateandtime: Optional[datetime.datetime] = None, with_refraction: bool = True) → float

Calculate the sun’s angle of elevation.

Parameters:
  • observer – Observer to calculate the solar elevation for
  • dateandtime – The date and time for which to calculate the angle. If dateandtime is None or is a naive Python datetime then it is assumed to be in the UTC timezone.
  • with_refraction – If True adjust elevation to take refraction into account
Returns:

The elevation angle in degrees above the horizon.

astral.sun.time_at_elevation(observer: astral.Observer, elevation: float, date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, tzinfo: Union[str, datetime.tzinfo] = datetime.timezone.utc, with_refraction: bool = True) → datetime.datetime

Calculates the time when the sun is at the specified elevation on the specified date.

Note

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:
  • elevation – Elevation of the sun in degrees above the horizon to calculate for.
  • observer – Observer to calculate for
  • date – Date to calculate for. Default is today’s date in the timezone tzinfo.
  • direction – Determines whether the calculated time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING. Default is rising.
  • tzinfo – Timezone to return times in. Default is UTC.
Returns:

Date and time at which the sun is at the specified elevation.

astral.moon

Moon rise and set times

Right ascension, declination and distance of moon calcaulation from

LOW-PRECISION FORMULAE FOR PLANETARY POSITIONS http://articles.adsabs.harvard.edu/pdf/1979ApJS…41..391V

astral.moon.phase(date: Optional[datetime.date] = None) → float

Calculates the phase of the moon on the specified date.

Parameters:date – The date to calculate the phase for. Dates are always in the UTC timezone. If not specified then today’s date is used.
Returns:A number designating the phase.
0 .. 6.99 New moon
7 .. 13.99 First quarter
14 .. 20.99 Full moon
21 .. 27.99 Last quarter

astral.geocoder

Astral geocoder is a database of locations stored within the package.

To get the LocationInfo for a location use the lookup() function e.g.

from astral.geocoder import lookup, database
l = lookup("London", database())

All locations stored in the database can be accessed using the all_locations generator

from astral.geocoder import all_locations
for location in all_locations:
    print(location)
astral.geocoder.lookup(name: str, db: Dict[str, Dict[str, List[astral.LocationInfo]]]) → Union[Dict[str, List[astral.LocationInfo]], astral.LocationInfo]

Look up a name in a database.

If a group with the name specified is a group name then that will be returned. If no group is found a location with the name will be looked up.

Parameters:
  • name – The group/location name to look up
  • db – The location database to look in
Raises:

KeyError – if the name is not found

astral.geocoder.database() → Dict[str, Dict[str, List[astral.LocationInfo]]]

Returns a database populated with the inital set of locations stored in this module

astral.geocoder.add_locations(locations: Union[str, List[str], List[List[str]], List[Tuple[str, ...]]], db: Dict[str, Dict[str, List[astral.LocationInfo]]]) → None

Add locations to the database.

Locations can be added by passing either a string with one line per location or by passing a list containing strings, lists or tuples (lists and tuples are passed directly to the LocationInfo constructor).

astral.geocoder.all_locations(db: Dict[str, Dict[str, List[astral.LocationInfo]]]) → Generator[astral.LocationInfo, None, None]

A generator that returns all the LocationInfos contained in the database

astral.location

class astral.location.Location(info: Optional[astral.LocationInfo] = None)

Provides access to information for single location.

blue_hour(direction: astral.SunDirection = <SunDirection.RISING: 1>, date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Tuple[datetime.datetime, datetime.datetime]

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:
  • direction – Determines whether the time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING. Default is rising.
  • date – The date for which to calculate the times. If no date is specified then the current date will be used.
  • local – True = Times to be returned in location’s time zone; False = Times to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

A tuple of the date and time at which the Blue Hour starts and ends.

dawn(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → datetime.datetime

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:
  • date – The date for which to calculate the dawn time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

The date and time at which dawn occurs.

daylight(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Tuple[datetime.datetime, datetime.datetime]

Calculates the daylight time (the time between sunrise and sunset)

Parameters:
  • date – The date for which to calculate daylight. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

A tuple containing the start and end times

dusk(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → datetime.datetime

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:
  • date – The date for which to calculate the dusk time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

The date and time at which dusk occurs.

golden_hour(direction: astral.SunDirection = <SunDirection.RISING: 1>, date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Tuple[datetime.datetime, datetime.datetime]

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:
  • direction – Determines whether the time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING. Default is rising.
  • date – The date for which to calculate the times.
  • local – True = Times to be returned in location’s time zone; False = Times to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

A tuple of the date and time at which the Golden Hour starts and ends.

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’[N|S] 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’[E|W] e.g. 51°31’W

For numbers, positive numbers signify longitudes to the East.

midnight(date: Optional[datetime.date] = None, local: bool = True) → datetime.datetime

Calculates the solar midnight (the time when the sun is at its lowest point.)

Parameters:
  • date – The date for which to calculate the midnight time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
Returns:

The date and time at which the solar midnight occurs.

moon_phase(date: Optional[datetime.date] = None, local: bool = True)

Calculates the moon phase for a specific date.

Parameters:date – The date to calculate the phase for. If ommitted the current date is used.
Returns:A number designating the phase
0 .. 6.99 New moon
7 .. 13.99 First quarter
14 .. 20.99 Full moon
21 .. 27.99 Last quarter
moonrise(date: Optional[datetime.date] = None, local: bool = True) → Optional[datetime.datetime]

Calculates the time when the moon rises.

Parameters:
  • date – The date for which to calculate the moonrise time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
Returns:

The date and time at which moonrise occurs.

moonset(date: Optional[datetime.date] = None, local: bool = True) → Optional[datetime.datetime]

Calculates the time when the moon sets.

Parameters:
  • date – The date for which to calculate the moonset time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
Returns:

The date and time at which moonset occurs.

night(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Tuple[datetime.datetime, datetime.datetime]

Calculates the night time (the time between astronomical dusk and astronomical dawn of the next day)

Parameters:
  • date – The date for which to calculate the start of the night time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

A tuple containing the start and end times

noon(date: Optional[datetime.date] = None, local: bool = True) → datetime.datetime

Calculates the solar noon (the time when the sun is at its highest point.)

Parameters:
  • date – The date for which to calculate the noon time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
Returns:

The date and time at which the solar noon occurs.

rahukaalam(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Tuple[datetime.datetime, datetime.datetime]

Calculates the period of rahukaalam.

Parameters:
  • date – The date for which to calculate the rahukaalam period. A value of None uses the current date.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC.
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

Tuple containing the start and end times for Rahukaalam.

solar_azimuth(dateandtime: Optional[datetime.datetime] = None, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → float

Calculates the solar azimuth angle for a specific date/time.

Parameters:dateandtime – The date and time for which to calculate the angle.
Returns:The azimuth angle in degrees clockwise from North.
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
solar_elevation(dateandtime: Optional[datetime.datetime] = None, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → float

Calculates the solar elevation angle for a specific time.

Parameters:dateandtime – The date and time for which to calculate the angle.
Returns:The elevation angle in degrees above the horizon.
solar_zenith(dateandtime: Optional[datetime.datetime] = None, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → float

Calculates the solar zenith angle for a specific time.

Parameters:dateandtime – The date and time for which to calculate the angle.
Returns:The zenith angle in degrees from vertical.
sun(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → Dict[str, Any]

Returns dawn, sunrise, noon, sunset and dusk as a dictionary.

Parameters:
  • date – The date for which to calculate the times. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

Dictionary with keys dawn, sunrise, noon, sunset and dusk whose values are the results of the corresponding methods.

sunrise(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → datetime.datetime

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:
  • date – The date for which to calculate the sunrise time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

The date and time at which sunrise occurs.

sunset(date: Optional[datetime.date] = None, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0) → datetime.datetime

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:
  • date – The date for which to calculate the sunset time. If no date is specified then the current date will be used.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

The date and time at which sunset occurs.

time_at_elevation(elevation: float, date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, local: bool = True) → datetime.datetime

Calculate the time when the sun is at the specified elevation.

Note

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:
  • elevation – Elevation in degrees above the horizon to calculate for.
  • date – The date for which to calculate the elevation time. If no date is specified then the current date will be used.
  • direction – Determines whether the time is for the sun rising or setting. Use SunDirection.RISING or SunDirection.SETTING. Default is rising.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
Returns:

The date and time at which dusk occurs.

timezone

The name of the time zone for the location.

A list of time zone names can be obtained from the zoneinfo module. For example.

>>> import zoneinfo
>>> assert "CET" in zoneinfo.available_timezones()
twilight(date: Optional[datetime.date] = None, direction: astral.SunDirection = <SunDirection.RISING: 1>, local: bool = True, observer_elevation: Union[float, Tuple[float, float]] = 0.0)

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:
  • direction – Determines whether the time is for the sun rising or setting. Use astral.SUN_RISING or astral.SunDirection.SETTING.
  • date – The date for which to calculate the times.
  • local – True = Time to be returned in location’s time zone; False = Time to be returned in UTC. If not specified then the time will be returned in local time
  • observer_elevation – Elevation of the observer in metres above the location.
Returns:

A tuple of the UTC date and time at which twilight starts and ends.

tz

Time zone information.

tzinfo

Time zone information.