are planning next year\u2019s birthday celebrations for three friends: Gabriel, Jacques, and Camille. All three of them were born in 1996, in Paris, France, so they will be 30 years old next year in 2026. Gabriel and Jacques will happen to be in Paris on their respective birthdays, while Camille will be in Tokyo, Japan, during hers. Gabriel and Camille tend to celebrate their birthdays in any given year on the \u201cofficial\u201d days mentioned on their birth certificates \u2014 January 18 and May 5, respectively. Jacques, who was born on February 29, prefers to celebrate his birthday (or civil anniversary) on March 1 in non-leap years.<\/p>\n
We use leap years to keep our calendar in sync with the Earth\u2019s orbit around the Sun. A solar year \u2014 the time it takes the Earth to complete one full orbit around the Sun \u2014 is approximately 365.25 days. By convention, the Gregorian calendar assigns 365 days to each year, except for leap years, which get 366 days to compensate for the fractional drift over time. This makes you wonder: will any of your friends be celebrating their birthday on the \u201creal\u201d anniversary of their day of birth, i.e., the day that the Sun will be in the same position in the sky (relative to the Earth) as it was when they were born? Could it be that your friends will end up celebrating turning 30 \u2014 a special milestone \u2014 a day too soon or a day too late?<\/p>\n
The following article uses this birthday problem to introduce readers to some interesting and broadly applicable open-source data science Python packages for astronomical computation and geospatial-temporal analytics, including skyfield, timezonefinder, geopy, and pytz. To gain hands-on experience, we will use these packages to solve our fun problem of accurately predicting the \u201creal birthday\u201d (or date of solar return) in a given future year. We will then discuss how such packages can be leveraged in other real-life applications.<\/p>\n
Real Birthday Predictor<\/p>\n
Project Setup<\/p>\n
All implementation steps below have been tested on macOS Sequoia 15.6.1 and should be roughly similar on Linux and Windows.<\/p>\n
Let us start by setting up the project directory. We will be using uv to manage the project (see installation instructions here<\/a>). Verify the installed version in the Terminal:<\/p>\n uv –version<\/p>\n Initialize a project directory called real-birthday-predictor at a suitable location on your local machine:<\/p>\n uv init –bare real-birthday-predictor<\/p>\n In the project directory, create a requirements.txt file with the following dependencies:<\/p>\n skyfield==1.53 Here is a brief overview of each of these packages:<\/p>\n We will also use a few other built-in modules, such as datetime for parsing and manipulating date\/time values, calendar for checking leap years, and time for sleeping between geocoding retries.<\/p>\n Next, create a virtual Python 3.12 environment inside the project directory, activate the environment, and install the dependencies:<\/p>\n uv venv –python=3.12 Check that the dependencies have been installed:<\/p>\n uv pip list<\/p>\n Implementation<\/p>\n In this section, we will go piece by piece through the code for predicting the \u201creal\u201d birthday date and time in a given future year and location of celebration. First, we import the necessary modules:<\/p>\n from datetime import datetime, timedelta Then we define the method, using meaningful variable names and docstring text:<\/p>\n def get_real_birthday_prediction( Note that current_country and current_city jointly refer to the location at which the birthday is to be celebrated in the target year.<\/p>\n We validate the inputs before working with them:<\/p>\n # Determine target year # Validate and parse birth date # Validate and parse birth time if not (0 <\/p>\n Next, we use geopy with the Nominatim geocoder to ascertain the birth and current locations. To avoid getting timeout errors, we set a reasonably long timeout value of ten seconds; this is how long our safe_geocode function waits for the geocoding service to respond before raising a geopy.exc.GeocoderTimedOut exception. To be extra safe, the function attempts the lookup procedure three times with one-second delays before giving up:<\/p>\n geolocator = Nominatim(user_agent=”birthday_tz_lookup”, timeout=10)<\/p>\n # Helper function to call geocode API with retries Using the geographical coordinates of the birth and current locations, we identify the respective time zones and the UTC date and time at birth. We also assume that individuals like Jacques, who were born on February 29, will prefer to celebrate their birthday on March 1 in non-leap years:<\/p>\n # Get time zones if not birth_tz_name or not current_tz_name: birth_tz = pytz.timezone(birth_tz_name) # Set civil anniversary date to March 1 for February 29 birthdays in non-leap years # Parse birth datetime in birth location’s local time Using the DE421 ephemeris data, we calculate where the Sun was (i.e., its ecliptic longitude) at the exact time and place the individual was born:<\/p>\n # Load ephemeris data and get Sun’s ecliptic longitude at birth # Birth longitude in tropical frame from POV of birth observer on Earth’s surface Note that, the first time the line eph = load(“de421.bsp”) is executed, the de421.bsp file will be downloaded and placed in the project directory; in all future executions, the downloaded file will be used directly. It is also possible to modify the code to load another ephemeris file (e.g., de440s.bsp, which covers years through January 22, 2150).<\/p>\n Now comes an interesting part of the function: we will make an initial guess of the \u201creal\u201d birthday date and time in the target year, define safe upper and lower bounds for the true date and time value (e.g., two days either side of the initial guess), and perform a binary search with early-stopping to efficiently home in on the true value:<\/p>\n # Initial guess for target year solar return # Compute Sun longitude from POV of current observer on Earth’s surface def sun_longitude_at(dt): def angle_diff(a, b): # Set safe upper and lower bounds for search space # Use binary search with early-stopping to solve for exact solar return in UTC real_dt_utc = dt1 + (dt2 – dt1) \/ 2<\/p>\n
\ntimezonefinder==8.0.0
\ngeopy==2.4.1
\npytz==2025.2<\/p>\n\n
\nsource .venv\/bin\/activate
\nuv add -r requirements.txt<\/p>\n
\nfrom skyfield.api import load, wgs84
\nfrom timezonefinder import TimezoneFinder
\nfrom geopy.geocoders import Nominatim
\nfrom geopy.exc import GeocoderTimedOut
\nimport pytz
\nimport calendar
\nimport time<\/p>\n
\n official_birthday: str,
\n official_birth_time: str,
\n birth_country: str,
\n birth_city: str,
\n current_country: str,
\n current_city: str,
\n target_year: str = None
\n):
\n “””
\n Predicts the “real” birthday (solar return) for a given year,
\n accounting for the time zone at the birth location and the time zone
\n at the current location. Uses March 1 in non-leap years for the civil
\n anniversary if the official birth date is February 29.
\n “””<\/p>\n
\n if target_year is None:
\n target_year = datetime.now().year
\n else:
\n try:
\n target_year = int(target_year)
\n except ValueError:
\n raise ValueError(f”Invalid target year ‘{target_year}’. Please use ‘yyyy’ format.”)<\/p>\n
\n try:
\n birth_date = datetime.strptime(official_birthday, “%d-%m-%Y”)
\n except ValueError:
\n raise ValueError(
\n f”Invalid birth date ‘{official_birthday}’. ”
\n “Please use ‘dd-mm-yyyy’ format with a valid calendar date.”
\n )<\/p>\n
\n try:
\n birth_hour, birth_minute = map(int, official_birth_time.split(“:”))
\n except ValueError:
\n raise ValueError(
\n f”Invalid birth time ‘{official_birth_time}’. ”
\n “Please use ‘hh:mm’ 24-hour format.”
\n )<\/p>\n
\n def safe_geocode(query, retries=3, delay=1):
\n for attempt in range(retries):
\n try:
\n return geolocator.geocode(query)
\n except GeocoderTimedOut:
\n if attempt <\/p>\n
\n tf = TimezoneFinder()
\n birth_tz_name = tf.timezone_at(lng=birth_location.longitude, lat=birth_location.latitude)
\n current_tz_name = tf.timezone_at(lng=current_location.longitude, lat=current_location.latitude)<\/p>\n
\n raise ValueError(“Could not determine timezone for one of the locations.”)<\/p>\n
\n current_tz = pytz.timezone(current_tz_name)<\/p>\n
\n birth_month, birth_day = birth_date.month, birth_date.day
\n if (birth_month, birth_day) == (2, 29):
\n if not calendar.isleap(birth_date.year):
\n raise ValueError(f”{birth_date.year} is not a leap year, so February 29 is invalid.”)
\n civil_anniversary_month, civil_anniversary_day = (
\n (3, 1) if not calendar.isleap(target_year) else (2, 29)
\n )
\n else:
\n civil_anniversary_month, civil_anniversary_day = birth_month, birth_day<\/p>\n
\n birth_local_dt = birth_tz.localize(datetime(
\n birth_date.year, birth_month, birth_day,
\n birth_hour, birth_minute
\n ))
\n birth_dt_utc = birth_local_dt.astimezone(pytz.utc)<\/p>\n
\n eph = load(“de421.bsp”) # Covers dates 1899-07-29 through 2053-10-09
\n ts = load.timescale()
\n sun = eph[“sun”]
\n earth = eph[“earth”]
\n t_birth = ts.utc(birth_dt_utc.year, birth_dt_utc.month, birth_dt_utc.day,
\n birth_dt_utc.hour, birth_dt_utc.minute, birth_dt_utc.second)<\/p>\n
\n birth_observer = earth + wgs84.latlon(birth_location.latitude, birth_location.longitude)
\n ecl = birth_observer.at(t_birth).observe(sun).apparent().ecliptic_latlon(epoch=’date’)
\n birth_longitude = ecl[1].degrees<\/p>\n
\n approx_dt_local_birth_tz = birth_tz.localize(datetime(
\n target_year, civil_anniversary_month, civil_anniversary_day,
\n birth_hour, birth_minute
\n ))
\n approx_dt_utc = approx_dt_local_birth_tz.astimezone(pytz.utc)<\/p>\n
\n current_observer = earth + wgs84.latlon(current_location.latitude, current_location.longitude)<\/p>\n
\n t = ts.utc(dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second)
\n ecl = current_observer.at(t).observe(sun).apparent().ecliptic_latlon(epoch=’date’)
\n return ecl[1].degrees<\/p>\n
\n return (a – b + 180) % 360 – 180<\/p>\n
\n dt1 = approx_dt_utc – timedelta(days=2)
\n dt2 = approx_dt_utc + timedelta(days=2)<\/p>\n
\n old_angle_diff = 999
\n for _ in range(50):
\n mid = dt1 + (dt2 – dt1) \/ 2
\n curr_angle_diff = angle_diff(sun_longitude_at(mid), birth_longitude)
\n if old_angle_diff == curr_angle_diff: # Early-stopping condition
\n break
\n if curr_angle_diff > 0:
\n dt2 = mid
\n else:
\n dt1 = mid
\n old_angle_diff = curr_angle_diff<\/p>\n