Astral v3.0 — Astral 3.0 documentation (2024)

Astral is a python package for calculating the times of various aspects ofthe sun and moon.

It can calculate the following

Dawn

The time in the morning when the sun is a specific number of degreesbelow the horizon.

Sunrise

The time in the morning when the top of the sun breaks the horizon(assuming a location with no obscuring features.)

Noon

The time when the sun is at its highest point directly above the observer.

Midnight

The time when the sun is at its lowest point.

Sunset

The time in the evening when the sun is about to disappear below thehorizon (asuming a location with no obscuring features.)

Dusk

The time in the evening when the sun is a specific number of degreesbelow the horizon.

Daylight

The time when the sun is up i.e. between sunrise and sunset

Night

The time between astronomical dusk of one day and astronomical dawn of thenext

Twilight

The time between dawn and sunrise or between sunset and dusk

The Golden Hour

The time when the sun is between 4 degrees below the horizon and 6 degreesabove.

The Blue Hour

The time when the sun is between 6 and 4 degrees below the horizon.

Time At Elevation

the time when the sun is at a specific elevation for either a rising or asetting sun.

Solar Azimuth

The number of degrees clockwise from North at which the sun can be seen

Solar Zenith

The angle of the sun down from directly above the observer

Solar Elevation

The number of degrees up from the horizon at which the sun can be seen

Rahukaalam

“Rahukaalam or the period of Rahu is a certain amount of time every daythat is considered inauspicious for any new venture according to IndianVedic astrology”.

Moonrise and Moonset

Like the Sun but for the moon

Moon Azimuth and Zenith

Also like the Sun but for the moon

Moon Phase

The phase of the moon for a specified date.

Astral also comes with a geocoder containing a local database that allows youto look up information for a small set of locations (new locations can beadded).

The following examples demonstrates some of the functionality available in themodule

from astral import LocationInfocity = LocationInfo("London", "England", "Europe/London", 51.5, -0.116)print(( f"Information for {city.name}/{city.region}\n" f"Timezone: {city.timezone}\n" f"Latitude: {city.latitude:.02f}; Longitude: {city.longitude:.02f}\n"))

Information for London/EnglandTimezone: Europe/LondonLatitude: 51.50; Longitude: -0.12

import datetimefrom astral.sun import suns = sun(city.observer, date=datetime.date(2009, 4, 22))print(( f'Dawn: {s["dawn"]}\n' f'Sunrise: {s["sunrise"]}\n' f'Noon: {s["noon"]}\n' f'Sunset: {s["sunset"]}\n' f'Dusk: {s["dusk"]}\n'))

Dawn: 2009-04-22 04:13:04.997608+00:00Sunrise: 2009-04-22 04:50:17.127004+00:00Noon: 2009-04-22 11:59:02+00:00Sunset: 2009-04-22 19:08:41.711407+00:00Dusk: 2009-04-22 19:46:06.423846+00:00

>>> city = LocationInfo("London", "England", "Europe/London", 51.5, -0.116)>>> london = Location(city)>>> s = sun(city.observer, date=datetime.date(2009, 4, 22), tzinfo=london.timezone)

>>> timezone = zoneinfo.ZoneInfo("Europe/London")>>> s = sun(city.observer, date=datetime.date(2009, 4, 22), tzinfo=timezone)

from astral import LocationInfocity = LocationInfo("London", "England", "Europe/London", 51.5, -0.116)import datetimefrom astral.moon import moonrisefrom astral.location import Locationdt = datetime.date(2021, 10, 28)london = Location(city)rise = moonrise(city.observer, dt) # returns a UTC timeprint(rise)

2021-10-28 22:02:00+00:00

rise = moonrise(city.observer, dt, city.tzinfo)

import datetimefrom astral import moonphase = moon.phase(datetime.date(2018, 1, 1))print(phase)

13.255666666666668

>>> from astral.geocoder import database, lookup>>> lookup("London", database())LocationInfo(name='London', region='England', timezone='Europe/London', latitude=51.473333333333336, longitude=-0.0008333333333333334)

from astral import LocationInfol = LocationInfo('name', 'region', 'timezone/name', 0.1, 1.2)

from astral import LocationInfol = LocationInfo()l.name = 'name'l.region = 'region'l.timezone = 'US/Central'l.latitude = 0.1l.longitude = 1.2

>>> from astral.geocoder import add_locations, database, lookup>>> db = database()>>> try:...  lookup("Somewhere", db)... except KeyError:...  print("Somewhere not found")...Somewhere not found>>> add_locations("Somewhere,Secret Location,UTC,24°28'N,39°36'E", db)>>> lookup("Somewhere", db)LocationInfo(name='Somewhere', region='Secret Location', timezone='UTC', latitude=24.466666666666665, longitude=39.6)

from astral.geocoder import group, databasedb = database()europe = group("europe", db)print(sorted(europe.keys())[:4])

['aberdeen', 'amsterdam', 'andorra_la_vella', 'ankara']

When viewing the sun the position you see it at is different from its actualposition due to the effect of atmospheric refraction whichmakes the sun appear to be higher in the sky. The calculations in thepackage take this refraction into account.

The sunrise() and sunset() functionsuse the refraction at an angle when the sun is half of its apparent diameterbelow the horizon. This is between about 30 and 32 arcminutes and for theastral package a value of 32” is used.

This module is licensed under the terms of the Apache V2.0 license.

To install Astral you should use the pip tool:

pip3 install astral

The module includes location and time zone data for the following cities.The list includes all capital cities plus some from the UK. The list alsoincludes the US state capitals and some other US cities.

Aberdeen, Abu Dhabi, Abu Dhabi, Abuja, Accra, Addis Ababa, Adelaide, Al Jubail,Albany, Albuquerque, Algiers, Amman, Amsterdam, Anchorage, Andorra la Vella,Ankara, Annapolis, Antananarivo, Apia, Ashgabat, Asmara, Astana, Asuncion,Athens, Atlanta, Augusta, Austin, Avarua, Baghdad, Baku, Baltimore, Bamako,Bandar Seri Begawan, Bangkok, Bangui, Banjul, Barrow-In-Furness, Basse-Terre,Basseterre, Baton Rouge, Beijing, Beirut, Belfast, Belgrade, Belmopan, Berlin,Bern, Billings, Birmingham, Birmingham, Bishkek, Bismarck, Bissau,Bloemfontein, Bogota, Boise, Bolton, Boston, Bradford, Brasilia, Bratislava,Brazzaville, Bridgeport, Bridgetown, Brisbane, Bristol, Brussels, Bucharest,Bucuresti, Budapest, Buenos Aires, Buffalo, Bujumbura, Burlington, Cairo,Canberra, Cape Town, Caracas, Cardiff, Carson City, Castries, Cayenne,Charleston, Charlotte, Charlotte Amalie, Cheyenne, Chicago, Chisinau,Cleveland, Columbia, Columbus, Conakry, Concord, Copenhagen, Cotonou, Crawley,Dakar, Dallas, Damascus, Dammam, Denver, Des Moines, Detroit, Dhaka, Dili,Djibouti, Dodoma, Doha, Douglas, Dover, Dublin, Dushanbe, Edinburgh, El Aaiun,Fargo, Fort-de-France, Frankfort, Freetown, Funafuti, Gaborone, George Town,Georgetown, Gibraltar, Glasgow, Greenwich, Guatemala, Hanoi, Harare,Harrisburg, Hartford, Havana, Helena, Helsinki, Hobart, Hong Kong, Honiara,Honolulu, Houston, Indianapolis, Islamabad, Jackson, Jacksonville, Jakarta,Jefferson City, Jerusalem, Juba, Jubail, Juneau, Kabul, Kampala, Kansas City,Kathmandu, Khartoum, Kiev, Kigali, Kingston, Kingston, Kingstown, Kinshasa,Koror, Kuala Lumpur, Kuwait, La Paz, Lansing, Las Vegas, Leeds, Leicester,Libreville, Lilongwe, Lima, Lincoln, Lisbon, Little Rock, Liverpool, Ljubljana,Lome, London, Los Angeles, Louisville, Luanda, Lusaka, Luxembourg, Macau,Madinah, Madison, Madrid, Majuro, Makkah, Malabo, Male, Mamoudzou, Managua,Manama, Manchester, Manchester, Manila, Maputo, Maseru, Masqat, Mbabane, Mecca,Medina, Melbourne, Memphis, Mexico, Miami, Milwaukee, Minneapolis, Minsk,Mogadishu, Monaco, Monrovia, Montevideo, Montgomery, Montpelier, Moroni,Moscow, Moskva, Mumbai, Muscat, N’Djamena, Nairobi, Nashville, Nassau,Naypyidaw, New Delhi, New Orleans, New York, Newark, Newcastle, Newcastle UponTyne, Ngerulmud, Niamey, Nicosia, Norwich, Nouakchott, Noumea, Nuku’alofa,Nuuk, Oklahoma City, Olympia, Omaha, Oranjestad, Orlando, Oslo, Ottawa,Ouagadougou, Oxford, P’yongyang, Pago Pago, Palikir, Panama, Papeete,Paramaribo, Paris, Perth, Philadelphia, Phnom Penh, Phoenix, Pierre, Plymouth,Podgorica, Port Louis, Port Moresby, Port of Spain, Port-Vila, Port-au-Prince,Portland, Portland, Porto-Novo, Portsmouth, Prague, Praia, Pretoria, Pristina,Providence, Quito, Rabat, Raleigh, Reading, Reykjavik, Richmond, Riga, Riyadh,Road Town, Rome, Roseau, Sacramento, Saint Helier, Saint Paul, Saint Pierre,Saipan, Salem, Salt Lake City, San Diego, San Francisco, San Jose, San Juan,San Marino, San Salvador, Sana, Sana’a, Santa Fe, Santiago, Santo Domingo, SaoTome, Sarajevo, Seattle, Seoul, Sheffield, Singapore, Sioux Falls, Skopje,Sofia, Southampton, Springfield, Sri Jayawardenapura Kotte, St. George’s, St.John’s, St. Peter Port, Stanley, Stockholm, Sucre, Suva, Swansea, Swindon,Sydney, T’bilisi, Taipei, Tallahassee, Tallinn, Tarawa, Tashkent, Tbilisi,Tegucigalpa, Tehran, Thimphu, Tirana, Tirane, Tokyo, Toledo, Topeka, Torshavn,Trenton, Tripoli, Tunis, Ulaanbaatar, Ulan Bator, Vaduz, Valletta, Vienna,Vientiane, Vilnius, Virginia Beach, W. Indies, Warsaw, Washington DC,Wellington, Wichita, Willemstad, Wilmington, Windhoek, Wolverhampton,Yamoussoukro, Yangon, Yaounde, Yaren, Yerevan, Zagreb, Zurich

The sun calculations in this module were adapted, for Python, from thespreadsheets on the following page.

https://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html

Refraction calculation is taken from

Sun-Pointing Programs and Their Accuracy

John C. Zimmerman Of Sandia National Laboratones

https://www.osti.gov/servlets/purl/6377969

Which cites the following as the original source

In Solar Energy Vol 20 No.5-C

Robert Walraven Of The University Of California, Davis

Moon position calculations from

LOW-PRECISION FORMULAE FOR PLANETARY POSITIONS

T. C. Van Flandern and K. F. Pulkkinen

And from

Astronomical Algorithms

Jean Meeus

The moon phase calculation is based on javascript codefrom Sky and Telescope magazine

Moon-phase calculation

Roger W. Sinnott, Sky & Telescope, June 16, 2006.

https://skyandtelescope.org/observing/the-phase-of-the-moon/

Also to Sphinx for making doc generation an easy thing (not that the writingof the docs is any easier.)

Simon Kennedy <sffjunkie+code@gmail.com>