Ephemeris Data #

The EphemerisDataFactory generates time-series planetary position data across date ranges. It is useful for tracking planetary movements, ingresses, and building ephemeris tables.

Basic Usage #

Generate daily planetary positions for a one-month period:

from datetime import datetime
from kerykeion import EphemerisDataFactory

factory = EphemerisDataFactory(
    start_datetime=datetime(2025, 1, 1),
    end_datetime=datetime(2025, 1, 31),
    step_type="days",
    step=1,
    lat=41.9028,
    lng=12.4964,
    tz_str="Europe/Rome",
)

data = factory.get_ephemeris_data()

# Each entry contains date, planets, and houses
for entry in data[:3]:
    print(f"Date: {entry['date']}")
    for planet in entry["planets"][:3]:
        print(f"  {planet['name']}: {planet['sign']} at {planet['position']:.2f}°")
    print()

Hourly Data #

Track faster-moving bodies with hourly resolution:

from datetime import datetime
from kerykeion import EphemerisDataFactory

factory = EphemerisDataFactory(
    start_datetime=datetime(2025, 3, 20, 0, 0),
    end_datetime=datetime(2025, 3, 21, 0, 0),
    step_type="hours",
    step=1,
    lat=51.5074,
    lng=-0.1278,
    tz_str="Europe/London",
)

data = factory.get_ephemeris_data()
print(f"Generated {len(data)} hourly data points")

# Track the Moon's movement through the day
for entry in data:
    moon = next(p for p in entry["planets"] if p["name"] == "Moon")
    print(f"{entry['date']}: Moon at {moon['position']:.4f}° {moon['sign']}")

Getting Full Subject Models #

Use get_ephemeris_data_as_astrological_subjects() to get full AstrologicalSubjectModel instances, giving access to all Kerykeion features for each time point:

from datetime import datetime
from kerykeion import EphemerisDataFactory

factory = EphemerisDataFactory(
    start_datetime=datetime(2025, 1, 1),
    end_datetime=datetime(2025, 1, 7),
    step_type="days",
    step=1,
    lat=41.9028,
    lng=12.4964,
    tz_str="Europe/Rome",
)

subjects = factory.get_ephemeris_data_as_astrological_subjects()

for subject in subjects:
    # subject.name is "Now" for every sample — the date is on the model itself
    print(f"{subject.iso_formatted_local_datetime[:10]}: "
          f"Sun in {subject.sun.sign}, Moon in {subject.moon.sign}")

Constructor Parameters #

Methods #

---