Astrologer API v5 Documentation #

Overview #

The Astrologer API v5 is a comprehensive engine designed for high-precision astrological calculations, professional-grade chart rendering, and AI-driven interpretations. It serves as a robust backend for astrology applications, enabling developers to integrate complex astrological features without needing deep domain expertise.

The API provides three main capabilities:

1. Ephemeris Calculations: Computes accurate positions of planets, house cusps, and other celestial points using the Swiss Ephemeris (via the Kerykeion library).
2. SVG Chart Generation: Generates high-quality, ready-to-display SVG charts for various astrological techniques (Natal, Synastry, Composite, Transits).
3. AI Context: Leverages Generative AI to provide textual explanations, syntheses, and personalized interpretations based on the calculated astrological data.

Core Concepts #

The “Subject” #

The fundamental unit of the API is the Subject. A Subject represents a specific entity (person, event, or moment) defined by a time and a location on Earth. Almost every endpoint requires one or more subject objects to perform calculations.

A typical subject object includes:

• Date & Time: Year, month, day, hour, minute.
• Location: City, nation, latitude, longitude.
• Timezone: IANA timezone string (e.g., “Europe/London”).
• Settings: Zodiac type (Tropical/Sidereal), house system, etc.

Chart Types #

The API supports several standard astrological chart types:

• Natal Chart: A map of the sky at a single moment (e.g., a birth).
• Synastry Chart: A bi-wheel chart comparing two subjects to analyze their relationship dynamics.
• Composite Chart: A single-wheel chart derived from the midpoints of two subjects, representing the relationship as a third entity.
• Transit Chart: A bi-wheel chart comparing a natal subject with the current (or future) sky to forecast trends.
• Solar/Lunar Returns: Charts calculated for the moment the Sun or Moon returns to its exact natal position.

Base URL #

All endpoints are prefixed with /api/v5.

Authentication #

Currently, the API is open for internal use. Future versions may require API keys or OAuth tokens.

Error Handling #

The API uses standard HTTP status codes:

• 200 OK: Success.
• 400 Bad Request: Invalid request parameters.
• 422 Unprocessable Entity: Validation error (e.g., invalid date or missing field).
• 500 Internal Server Error: Unexpected server error.

Documentation Index #

📊 Data Endpoints (JSON) #

Endpoints that return raw calculated data (JSON) without visual charts. Ideal for custom frontend rendering or data analysis.

• Subject (Example): Calculate a subject’s astrological data.
• Now Subject (Example): Get the astrological data for the current moment.
• Compatibility Score (Example): Calculate a numerical compatibility score between two people.
• Chart Data:
  • Natal Chart Data (Example)
  • Synastry Chart Data (Example)
  • Composite Chart Data (Example)
  • Transit Chart Data (Example)
  • Solar Return Data (Example)
  • Lunar Return Data (Example)

🎨 Chart Endpoints (SVG) #

Endpoints that return rendered SVG charts along with the calculation data.

• Natal Chart (Example)
• Now Chart (Example)
• Synastry Chart (Example)
• Composite Chart (Example)
• Transit Chart (Example)
• Solar Return Chart (Example)
• Lunar Return Chart (Example)

🧠 Context Endpoints (AI) #

Endpoints that return AI-optimized textual interpretations and context.

• Subject Context (Example)
• Now Context (Example)
• Natal Chart Context (Example)
• Synastry Context (Example)
• Composite Context (Example)
• Transit Context (Example)
• Solar Return Context (Example)
• Lunar Return Context (Example)

---

Note: Miscellaneous endpoints (health checks) are available but not documented here.