Zodiac Engine: Astrological Calculation & Visualization API
A modern, high-performance API for astrological calculations and chart visualizations, powered by the Kerykeion library and built with FastAPI. Features natal charts, synastry, composites, transits, and LLM-powered interpretations.
Q1 2024 - Present (Ongoing Development)
Project Overview
The Zodiac Engine offers a comprehensive suite of astrological tools through a clean, developer-friendly REST API. It leverages the precision of the Kerykeion library for core calculations and extends its capabilities with enhanced SVG visualizations and an architecture designed for integrating AI-driven interpretations. The goal is to provide a robust, scalable, and modern platform for both enthusiasts and professional astrology applications.
The Challenge
Existing astrological tools and libraries often present challenges such as outdated interfaces, complex integration, limited feature sets for advanced analysis (like detailed synastry or AI interpretations), or lack of modern API design. Developers and researchers need a reliable, performant, and easily integrable service for complex astrological computations and high-quality chart rendering.
The Solution
I developed the Zodiac Engine as a FastAPI-based microservice that wraps and enhances the Kerykeion library. It provides a well-documented REST API for various chart types (natal, synastry, composite, transit), customizable SVG chart generation, and a service layer architected for future integration with Large Language Models (LLMs) for chart interpretations. The focus is on accuracy, developer experience, and modern application needs.
Key Features
Advanced capabilities that make this project stand out
Comprehensive Natal Charts
Calculate detailed natal charts including planetary positions, house cusps, aspects (with orbs), lunar nodes, Lilith, and Chiron using various house systems.
Advanced Chart Visualization
Generate high-quality, customizable SVG visualizations for natal and synastry charts. Supports multiple themes (dark, light, classic) and languages.
Synastry & Composite Charts
Endpoints for calculating synastry (relationship compatibility) and composite (midpoint) charts, with planned detailed analysis features.
Transit Calculations
Calculate planetary transits for specific dates to understand current or future astrological influences on a natal chart (endpoint planned).
LLM-Powered Interpretations
Generate textual interpretations of natal and synastry charts using integrated Large Language Models (Gemini, OpenAI). Customizable focus areas, tone, and length.
Report Generation
Produce detailed textual reports in ASCII table format for natal and synastry charts, suitable for direct display or as LLM input.
Technical Deep Dive
The implementation details, architecture decisions, and technology choices
The Zodiac Engine is a FastAPI application serving a REST API. It follows a service-oriented architecture with distinct services for astrology calculations (wrapping Kerykeion), chart visualization (KerykeionSVG & custom processing), geolocation (GeoNames), report generation (Kerykeion Report), and LLM-based interpretations. Data validation is handled by Pydantic schemas. SVG charts and other static assets are served via FastAPI's StaticFiles. An HTMX/Jinja2 frontend provides a web interface for basic interactions.
Project Gallery
Visual showcase of the project deliverables and implementation
/assets/case-studies/zodiac-engine/code/openapi.json
OpenAPI Schema Definition for Zodiac Engine API
Code Sample
Zodiac Engine System Architecture Diagram (Mermaid)
Image
Creating and Customizing Natal Charts
Video
LLM-Powered Chart Interpretation
Video
Generating Detailed Astrological Reports
Video
Swagger UI Documentation Interface
Image
Outcomes & Impact
Results delivered, lessons learned, and future directions
Modern & Accurate Astrological API
Successfully created a state-of-the-art API providing comprehensive astrological calculations and visualizations with a developer-friendly interface.
Key Metrics:
- Extensive endpoint coverage for core astrological charts
- Sub-100ms average calculation time for natal charts (cached)
- High accuracy based on Kerykeion library precision
Customizable Chart Generation
Empowered users with significant control over chart appearance (themes, languages) and calculation parameters (house systems, zodiac types, active points/aspects).
Key Metrics:
- Multiple themes & languages supported
- Configurable house systems & zodiac types
- Fine-grained control over displayed celestial points and aspects
Foundation for AI Interpretations
Established a solid backend capable of generating structured astrological data suitable for input into LLMs, paving the way for advanced AI-powered chart interpretations.
Key Metrics:
- Structured report generation for LLM input
- LLM service integration (Gemini initial, OpenAI/Anthropic planned)
- Customizable interpretation parameters (focus, tone, length)
Key Learnings
- FastAPI is highly effective for building performant and well-documented APIs, especially with Pydantic v2.
- Integrating specialized libraries like Kerykeion requires careful API design to abstract complexity while exposing necessary functionality.
- Preprocessing SVGs (e.g., inlining CSS variables) is crucial for ensuring their portability and compatibility with conversion tools like CairoSVG.
- Background tasks in FastAPI are essential for offloading time-consuming operations like SVG generation, improving API responsiveness.
- Crafting effective prompts for LLMs is a critical skill for generating meaningful astrological interpretations.
- Caching external API calls (e.g., GeoNames) significantly improves performance and reliability.
- Managing different chart configurations (Tropical vs. various Sidereal modes, house systems) requires robust data models and clear API parameters.
Future Enhancements
- Full implementation of Composite and Transit chart calculation/visualization endpoints.
- Enhanced LLM interpretation capabilities with more nuanced astrological understanding and user feedback loops.
- Interactive frontend chart exploration tools (beyond the basic HTMX UI).
- User authentication and saved chart management.
- Database persistence for user data and generated charts (currently in-memory cache/static files).
- Expanded support for more astrological points (asteroids, fixed stars) and techniques (midpoints, harmonics).
- Websocket integration for real-time chart updates or interactive features.
Get In Touch
I'm always open to discussing new projects, opportunities or partnerships.
Send a Message
How can I help you? Fill out the form below.
Connect With Me
I'm always open to discussing new projects, opportunities, or collaborations.