Subscribe to support and grow the project.
Data Driven
Astrology 💫
Compute precise astrological data, detect aspects, and render beautiful SVG charts with a modern, type-safe Python library. Upgrade to the hosted AstrologerAPI to scale instantly.
pip install kerykeion
Why Developers Choose Kerykeion
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.
Upgrade Path — AstrologerAPI
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 AstrologerAPI — it's AGPL-compliant and supports the project.
Library (AGPL-3.0)
Use freely in compatible open-source projects
Hosted API
Integrate without open-sourcing your code
Ready to Get Started?
Star the repo if Kerykeion helped you. Your support drives new features, improved docs, and more chart themes.
Current Transits
Current planetary positions and lunar phase
| Planet | Position | Sign | Speed | Declination |
|---|---|---|---|---|
Name Phase Day | ||||