Data Driven
Astrology 💫
Compute precise astrological data, detect aspects, and render beautiful SVG charts with a modern, type-safe Python library.
Try Astrologer API
Use Astrologer API to add natal charts, synastry, transits, and AI context to your app — no Python required.
Subscribing helps support the project and keeps it growing!
Discover Astrologer Studio
A complete professional astrology environment and client management system. Generate high-precision charts, manage your clients, and get AI-powered insights.
Built on Kerykeion technology, designed for professional astrologers.
Why Developers Choose Kerykeion
A modern Python astrology library, hosted Astrologer API, and thousands of free guides for developers and astrology enthusiasts.
Beautiful Charts
Fast SVG rendering with themes, i18n, wheel-only and grid-only modes
Data First
Factory architecture separates calculations from rendering for clarity and testability
Precise Astronomy
Swiss Ephemeris (NASA JPL) under the hood for positions, motion, and declination
Type-Safe Models
Pydantic 2 data classes for subjects, aspects, distributions, and returns
Flexible Analysis
Natal, synastry, transit, composite, solar and lunar returns
Works Offline
Provide lng, lat, and tz_str to avoid network calls entirely
Quick Example
Build an AstrologicalSubject
Create a subject from birth or event data. You can use offline coordinates or leverage the built-in GeoNames integration for automatic lookup.
Use ChartDataFactory
Generate all necessary astronomical calculations, including planetary positions, house cusps, aspects, and element distributions.
Render an SVG
Visualize the data using ChartDrawer to create beautiful, customizable SVG charts, or generate detailed text reports.
from pathlib import Path
from kerykeion import AstrologicalSubjectFactory
from kerykeion.chart_data_factory import ChartDataFactory
from kerykeion.charts.chart_drawer import ChartDrawer
# Create a subject from birth data (offline example with manual coordinates)
subject = AstrologicalSubjectFactory.from_birth_data(
"Kanye", 1977, 6, 8, 8, 45,
lng=-84.38798,
lat=33.7490,
tz_str="America/New_York",
online=False,
)
# Pre-compute natal chart data (calculations only)
chart_data = ChartDataFactory.create_natal_chart_data(subject)
# Render and save the SVG
drawer = ChartDrawer(chart_data=chart_data)
out_dir = Path("charts_output")
out_dir.mkdir(exist_ok=True)
drawer.save_svg(output_path=out_dir, filename="kanye-natal")
Upgrade Path — Astrologer API
Building a commercial or closed-source app? Prefer serverless scale and language-agnostic integration? Use the hosted API.
Features At A Glance
Calculations
- Planet and point positions (with daily motion and declination)
- Houses with multiple systems (default: Placidus)
- True/Mean Nodes, Lilith, Chiron, angles, asteroids and TNOs
- Single-chart and dual-chart aspects with orb controls
Analysis
- Element and quality distributions (weighted or pure-count)
- Customizable weighting per point with fallback
- Synastry extras: relationship score and house overlays
Rendering
- Full charts, wheel-only, or aspect-grid-only as SVG
- Themes: classic, dark, light, strawberry, black-and-white
- Internationalization: EN, FR, PT, ES, TR, RU, IT, CN, DE
Configuration
- Tropical or Sidereal (e.g., LAHIRI) zodiac
- House systems (Placidus default, others supported)
- Multiple perspective types (Geocentric, Heliocentric, etc.)
AI-Ready Astrological Context
Bridge the gap between raw astrological data and Large Language Models. The new context_serializer module transforms complex charts into precise, hallucination-free text descriptions optimized for AI consumption.
Optimized for LLMs
Structured, non-qualitative output designed to be injected directly into system prompts for ChatGPT, Claude, and other models.
Comprehensive Support
Works with Natal, Synastry, Composite, Transit, and Return charts. Get consistent, type-safe descriptions for any astrological subject.
Chart for John Doe
Birth data: 1990-01-01 12:00, London, GB
Coordinates: 51.51°N, -0.13°W
Timezone: Europe/London
Zodiac system: Tropical
House system: Placidus
Celestial Points:
- Sun at 10.81° in Capricorn in Tenth House
quality: Cardinal, element: Earth
direct motion, speed 1.0195°/day
- Moon at 25.60° in Aquarius in Eleventh House
quality: Fixed, element: Air
direct motion, speed 12.4796°/day
...Showcase
Here are some examples of the charts you can generate.
Common Use Cases
Product features: embeddable charts and reports
Research & analytics: programmatic aspect mining
Publishing: B/W theme for crisp prints and PDFs
Generative AI: structured JSON models and SVGs
Licensing & Commercial Use
Kerykeion is AGPL-3.0. If you link the library in your app, your app must be open-source under a compatible license. If you need to keep your source closed, use the hosted Astrologer API — it's AGPL-compliant and supports the project.
Hosted API
RecommendedCommercial Use
Integrate in closed-source and commercial applications without licensing concerns
Library (AGPL-3.0)
Open Source
Use freely in compatible open-source projects
Frequently Asked Questions
Learn Astrology
Master the symbolic language of the stars with our comprehensive collection of 300+ free guides. From birth charts to transits, start your journey today.
Natal Charts
Understand planets, houses, and aspects in your birth chart
50+ guidesSynastry
Explore relationship compatibility and dynamics
60+ guidesComposite Charts
Discover the relationship as its own entity
40+ guidesTransits
Track planetary movements and their effects
100+ guidesSolar Returns
Annual themes and yearly predictions
15+ guidesLunar Returns
Monthly emotional cycles and rhythms
15+ guidesLearn Tarot
Explore the wisdom of tarot with our complete collection of 78 card guides. Understand the symbolism, meanings, and interpretations.
Major Arcana
The Fool's journey through life's major lessons and archetypes
22 cardsWands
Fire element: passion, creativity, ambition, and spiritual growth
14 cardsCups
Water element: emotions, relationships, intuition, and love
14 cardsSwords
Air element: intellect, conflict, truth, and mental challenges
14 cardsPentacles
Earth element: material world, career, health, and finances
14 cardsSpreads & Readings
How to lay out cards and interpret them in context
10+ guidesStart Building Better Astrology Apps
Stop wrestling with complex calculations. Get precise, high-performance astrology data and beautiful charts in minutes with Kerykeion.