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.

Parameter	Type	Default	Description
`as_model`	`bool`	`False`	If `True`, returns `EphemerisDictModel` instances instead of dicts.

Output Structure:

[
  {
    "date": "2024-01-01T00:00:00",
    "planets": [
      { "name": "Sun", "abs_pos": 280.23, "sign": "Cap", ... },
      ...
    ],
    "houses": [
      { "name": "First_House", "abs_pos": 15.42, "sign": "Ari", ... },
      ...
    ]
  },
  ...
]

`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.).

Parameter	Type	Default	Description
`as_model`	`bool`	`False`	Accepted for signature compatibility (currently unused).

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

Configuration #

Time Parameters #

Parameter	Description	Options
`step_type`	Unit of time step	`"days"`, `"hours"`, `"minutes"`
`step`	Multiplier for step type	Integer (e.g. `1`, `7`)
`max_days`	Safety limit for daily data	Default: 730
`max_hours`	Safety limit for hourly data	Default: 8760
`max_minutes`	Safety limit for minute data	Default: 525600

Location Parameters #

Parameter	Description	Default
`lat`	Latitude for house cusps	`51.4769` (London)
`lng`	Longitude for house cusps	`0.0005`
`tz_str`	Timezone string	`"Etc/UTC"`
`is_dst`	Daylight saving time flag	`False`

Calculation Parameters #

Parameter	Description	Default
`zodiac_type`	Tropical or Sidereal	`"Tropical"`
`sidereal_mode`	Ayanamsa mode (if Sidereal)	`None`
`houses_system_identifier`	House system code	`"P"` (Placidus)
`perspective_type`	Calculation perspective	`"Apparent Geocentric"`
`custom_ayanamsa_t0`	Reference epoch (Julian Day) for USER sidereal mode	`None`
`custom_ayanamsa_ayan_t0`	Ayanamsa offset in degrees at epoch (USER mode)	`None`

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".

Need this in production? Use the Astrologer API for hosted calculations, charts, and AI interpretations - no server setup required. Learn more →