Try Astrologer API

Subscribe to support and grow the project.

Kerykeion

Kerykeion Documentation #

Kerykeion is a production-grade Python library for computational astrology. It provides high-precision planetary and house position calculations (via the Swiss Ephemeris), aspect detection, relationship scoring, transit forecasting, and professional SVG chart generation – all with a clean, factory-based API and Pydantic models.

What you can do with Kerykeion #

  • Calculate positions for 63+ celestial points (planets, asteroids, TNOs, fixed stars, Arabic parts)
  • Generate professional SVG charts in 6 themes, 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 kerykeion

Requires Python 3.9 or higher.

Quick Start #

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
from kerykeion.charts.chart_drawer import 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.54°
Moon: Sco at 15.32°
Ascendant: Vir
Sun absolute position: 112.54°

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 #

Analysis #

Forecasting #

Reference #

  • Types & Schemas: Complete Pydantic model and type reference.
  • Active Points: Reference for all 63 celestial points and preset configurations.
  • 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.
  • Legacy API: Backward compatibility layer for v4 users.

Integration #