Try Astrologer API

Subscribe to support and grow the project.

Kerykeion

Kerykeion Documentation #

Kerykeion is a Python library for computational astrology. This documentation targets 6.0.3, a stable v6 maintenance release. It provides planetary and house position calculations (via libephemeris, with optional Swiss Ephemeris backend), aspect detection, relationship scoring, transit forecasting, and SVG chart generation with a factory-based API and Pydantic models.

What you can do with Kerykeion #

  • Calculate positions for 53 chart points (planets, asteroids, TNOs, Uranian points, Arabic parts) plus fixed stars from a 1,447-name catalog
  • Generate professional SVG charts in 3 themes (plus theme=None), 2 styles, and 10 languages
  • Analyze aspects, element/quality distributions, and relationship compatibility
  • Forecast with solar/lunar returns, transits over time ranges, and ephemeris data
  • Integrate with AI/LLMs via structured XML context serialization
  • Export everything as JSON via Pydantic models

Building a production app? Skip the server setup with Astrologer API – get charts, calculations, and AI interpretations via REST API. Learn more

Installation #

pip install --upgrade "kerykeion"

Requires Python 3.12 or higher.

For v4/v5 upgrades, follow the migration guide; v6 changes calculation defaults and removes deprecated APIs.

Quick Start #

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer

# Create an astrological subject (offline mode with explicit coordinates)
subject = AstrologicalSubjectFactory.from_birth_data(
    "John Doe", 1990, 7, 15, 10, 30,
    lng=12.4964, lat=41.9028, tz_str="Europe/Rome",
    online=False
)

# Access planetary positions
print(f"Sun: {subject.sun.sign} at {subject.sun.position:.2f}°")  # position = 0-30° within sign
print(f"Moon: {subject.moon.sign} at {subject.moon.position:.2f}°")
print(f"Ascendant: {subject.first_house.sign}")
print(f"Sun absolute position: {subject.sun.abs_pos:.2f}°")  # abs_pos = 0-360° on zodiac

# Generate an SVG chart
chart_data = ChartDataFactory.create_natal_chart_data(subject)
drawer = ChartDrawer(chart_data)
svg_string = drawer.generate_svg_string()

Output:

Sun: Can at 22.61°
Moon: Ari at 21.21°
Ascendant: Vir
Sun absolute position: 112.61°

position vs abs_pos: Every celestial point has two position fields. position is the degree within its sign (0-30°), while abs_pos is the absolute ecliptic longitude (0-360°). Use position for display and abs_pos for calculations.

For more examples, see the Examples Gallery.

Getting Started #

Core #

  • Astrological Subject Factory: Creating astrological subjects from birth data, ISO timestamps, or current time.
  • Chart Data Factory: Calculating structured chart data for natal, synastry, transit, composite, and return charts.
  • Charts Module: Rendering professional SVG charts with ChartDrawer, in the modern or classic style and at three planet-cluster sizes (glyph_size).
  • Chart Glyphs: Visual reference for every glyph rendered in charts (planets, points, signs, aspects).
  • Report Module: Generating human-readable text reports.

Analysis #

Forecasting #

Advanced Calculations #

Reference #

  • Types & Schemas: Complete Pydantic model and type reference.
  • Active Points: Reference for the 53 non-star chart points, separately configured fixed stars, and their presets.
  • Cookbook: Practical recipes and code snippets for common tasks.
  • Constants: Exhaustive lists of points, aspects, and preset constants.
  • Utilities: Helper functions for zodiac math, Julian Day, and SVG processing.
  • Settings: Global configuration, translation utilities, and presets.
  • Chart Internals: Low-level SVG rendering functions (advanced).
  • Fetch Geonames: GeoNames API integration for location resolution.
  • Ephemeris Backend: Backend configuration (libephemeris vs Swiss Ephemeris).
  • Backend Precision Comparison: Numerical and behavioral differences between the two backends.
  • Swiss Ephemeris Configuration: Optional Swiss Ephemeris backend setup, fixed-star catalog, and precision notes.
  • Legacy API: Migration info for v4/v5 users (removed in v6).

Integration #