Ephemeris Data Factory #

The EphemerisDataFactory generates time-series astrological data (ephemerides) for a specified date range and interval.

Basic Usage #

Initialize the factory with a start and end datetime to generate a list of planetary positions.

from datetime import datetime
from kerykeion import EphemerisDataFactory

# 1. Define Range (must be datetime objects)
start = datetime(2024, 1, 1)
end = datetime(2024, 1, 31)

# 2. Initialize Factory
factory = EphemerisDataFactory(
    start_datetime=start,
    end_datetime=end,
    step_type="days", # "days", "hours", or "minutes"
    step=1, # Interval size
    lat=51.5074,
    lng=-0.1278,
    tz_str="Europe/London"
)

# 3. Get Data (List of Dictionaries)
data = factory.get_ephemeris_data()
print(f"Sun 1st Day: {data[0]['planets'][0]['abs_pos']:.2f}°")

Note: The constructor parameters are named start_datetime and end_datetime and must be Python datetime objects (not date objects).

Methods #

get_ephemeris_data(as_model=False) #

Returns a list of dictionaries (or EphemerisDictModel instances if as_model=True). Fast and lightweight. Best for raw data processing.

Every sample dict always carries date, planets, houses, ephemeris_warnings and polar_house_fallbacks keys. The last two are always present and empty when there is nothing to report, so consumers can read them unconditionally instead of guessing. polar_house_fallbacks holds PolarHouseFallbackModel entries for any sample whose house cusps could not be computed with the requested system at the requested latitude — see Polar Latitudes for what a substitution changes and what it leaves exact.

A fixed_stars key is added to each sample only when the factory was built with a non-empty active_fixed_stars list; without requested stars the key is omitted entirely.

The planets and houses lists hold KerykeionPointModel instances – not plain dicts – which support both attribute access (point.abs_pos) and dictionary-style subscripting (point["abs_pos"]).

date is the UTC instant of the sample, serialised with datetime.isoformat() from a timezone-aware datetime, so it always ends in the +00:00 offset.

Output Structure:

[
  {
    "date": "2024-01-01T00:00:00+00:00",
    "planets": [
      KerykeionPointModel(name="Sun", abs_pos=280.04, sign="Cap", ...),
      ...
    ],
    "houses": [
      KerykeionPointModel(name="First_House", abs_pos=187.07, sign="Lib", ...),
      ...
    ],
    "ephemeris_warnings": [],
    "polar_house_fallbacks": [],  # PolarHouseFallbackModel entries, empty at temperate latitudes
    # "fixed_stars": [...]  # present only when active_fixed_stars is non-empty
  },
  ...
]

get_ephemeris_data_as_astrological_subjects(as_model=False) #

Returns a list of full AstrologicalSubjectModel objects. Slower but provides full analysis capabilities (aspects, houses, etc.).

subjects = factory.get_ephemeris_data_as_astrological_subjects()
print(subjects[0].sun.sign)

Configuration #

Time Parameters #

Location Parameters #

Naive inputs are local wall times. Daily samples advance by local calendar days; hourly and minutely samples advance uniformly in UTC. Before a zone has any recorded civil time, a synthetic IANA LMT record is replaced by local mean time at the supplied longitude, exactly as in AstrologicalSubjectFactory. Named historical records such as RMT or BMT remain authoritative.

Calculation Parameters #

Note: You can override safety limits by passing None if you need large datasets. Both custom_ayanamsa_t0 and custom_ayanamsa_ayan_t0 are required when sidereal_mode="USER".

Raises #

The constructor raises ValueError for a non-positive step, for an unknown step_type, when the sample count exceeds the max_days / max_hours / max_minutes limit in force, and – as "No dates found. Check the date range and step values." – when the range yields no sample at all, which is what an inverted range (end_datetime before start_datetime) produces.

Note: When feeding TransitsTimeRangeFactory with non-default points (asteroids, TNOs, extra angles), pass the same active_points list here — aspects can only be detected for points present on both the natal and the ephemeris subjects; the transit factory warns if a requested point is present on only one side (missing from the ephemeris series or from the natal chart).

---