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, Solar/Lunar Returns, Now).
3. AI Context: Leverages Generative AI to provide XML-structured explanations, syntheses, and personalized interpretations based on the calculated astrological data.

Base URL #

https://astrologer.p.rapidapi.com/api/v5

All endpoints are prefixed with /api/v5.

Authentication #

The API is served through RapidAPI. Every request must include two headers:

You can obtain an API key by subscribing to the Astrologer API on the RapidAPI marketplace.

Example request:

curl -X POST "https://astrologer.p.rapidapi.com/api/v5/subject" \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: astrologer.p.rapidapi.com" \
  -d '{ "subject": { "name": "John", "year": 1990, "month": 1, "day": 15, "hour": 12, "minute": 30, "city": "London", "nation": "GB", "longitude": -0.1276, "latitude": 51.5074, "timezone": "Europe/London" } }'

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.

Subject Object Reference #

Location resolution: You must provide location in one of two ways:

1. Coordinates (offline, recommended): Supply all three of latitude, longitude, and timezone.
2. GeoNames (online): Supply geonames_username with city and nation. The API resolves coordinates automatically. If both are provided, GeoNames takes priority and coordinates are cleared.

Transit Subject #

Transit endpoints use a simplified subject model (transit_subject) that does not include zodiac_type, sidereal_mode, perspective_type, or houses_system_identifier. These settings are inherited from the natal first_subject. The name field defaults to "Transit".

Chart Types #

The API supports the following chart types:

• Natal Chart: A map of the sky at a single moment (e.g., a birth).
• Now Chart: A natal chart for the current UTC moment at Greenwich Observatory.
• 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 a transit moment to forecast trends.
• Solar/Lunar Returns: Charts calculated for the moment the Sun or Moon returns to its exact natal position.

Computation Options #

All data, chart, and context endpoints that compute chart data accept these optional configuration fields at the request body root level (not inside subject):

Rendering Options #

Chart (SVG) endpoints additionally accept these rendering fields:

Error Handling #

The API uses standard HTTP status codes:

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

Error response body:

All error responses return JSON with the following structure:

{
  "status": "ERROR",
  "message": "Descriptive error message explaining what went wrong.",
  "error_type": "ValueError"
}

GeoNames-specific errors (city/nation resolution failures) return a standardized message with instructions:

{
  "status": "ERROR",
  "message": "City/Nation name error or invalid GeoNames username. Please check your username or city name and try again. You can create a free username here: https://www.geonames.org/login/. If you want to bypass the usage of GeoNames, please remove the geonames_username field from the request. Note: The nation field should be the country code (e.g. US, UK, FR, DE, etc.)."
}

Configuration Reference #

Themes #

Languages #

House Systems #

Perspective Types #

Sidereal Modes #

Required when zodiac_type is "Sidereal". 48 modes available:

Indian / Vedic: LAHIRI, LAHIRI_1940, LAHIRI_ICRC, LAHIRI_VP285, KRISHNAMURTI, KRISHNAMURTI_VP291, RAMAN, USHASHASHI, JN_BHASIN, YUKTESHWAR, ARYABHATA, ARYABHATA_522, ARYABHATA_MSUN, SURYASIDDHANTA, SURYASIDDHANTA_MSUN, SS_CITRA, SS_REVATI, TRUE_CITRA, TRUE_MULA, TRUE_PUSHYA, TRUE_REVATI, TRUE_SHEORAN

Western Sidereal: FAGAN_BRADLEY, DELUCE, DJWHAL_KHUL, HIPPARCHOS, SASSANIAN

Babylonian: BABYL_KUGLER1, BABYL_KUGLER2, BABYL_KUGLER3, BABYL_HUBER, BABYL_ETPSC, BABYL_BRITTON

Galactic Alignment: GALCENT_0SAG, GALCENT_COCHRANE, GALCENT_MULA_WILHELM, GALCENT_RGILBRAND, GALEQU_FIORENZA, GALEQU_IAU1958, GALEQU_MULA, GALEQU_TRUE, GALALIGN_MARDYKS

Reference Frames: J2000, J1900, B1950

Astronomical: ALDEBARAN_15TAU, VALENS_MOON

User-Defined: USER – Requires custom_ayanamsa_t0 (Julian Day of reference epoch) and custom_ayanamsa_ayan_t0 (ayanamsa offset in degrees at that epoch).

Active Points #

The default preset includes 18 points. You can override with any combination of the 63 available points:

Planets (10): Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto

Lunar Nodes (4): Mean_North_Lunar_Node, True_North_Lunar_Node, Mean_South_Lunar_Node, True_South_Lunar_Node

Special Points (5): Chiron, Mean_Lilith, True_Lilith, Earth, Pholus

Asteroids (4): Ceres, Pallas, Juno, Vesta

Trans-Neptunian Objects (7): Eris, Sedna, Haumea, Makemake, Ixion, Orcus, Quaoar

Fixed Stars (23): Regulus, Spica, Aldebaran, Antares, Sirius, Fomalhaut, Algol, Betelgeuse, Canopus, Procyon, Arcturus, Pollux, Deneb, Altair, Rigel, Achernar, Capella, Vega, Alcyone, Alphecca, Algorab, Deneb_Algedi, Alkaid

Arabic Parts (4): Pars_Fortunae, Pars_Spiritus, Pars_Amoris, Pars_Fidei

Angular Points (6): Ascendant, Medium_Coeli, Descendant, Imum_Coeli, Vertex, Anti_Vertex

Accepted aliases (case-insensitive): asc = Ascendant, mc = Medium_Coeli, ic = Imum_Coeli, desc = Descendant, lilith = Mean_Lilith, north_node = Mean_North_Lunar_Node, south_node = Mean_South_Lunar_Node, mean_node = Mean_North_Lunar_Node, true_node = True_North_Lunar_Node, mean_south_node = Mean_South_Lunar_Node, true_south_node = True_South_Lunar_Node

Active Aspects #

The default preset includes 6 aspects. All 11 are available:

Note: Aspect names are lowercase in both request and response payloads.

Sign Abbreviations #

Response payloads use three-letter abbreviations for zodiac signs:

Response Key Naming #

Most context endpoints return the AI text in a field called context. Two exceptions use subject_context instead:

• POST /api/v5/context/subject – returns subject_context + subject
• POST /api/v5/now/context – returns subject_context + subject

All other context endpoints return context + chart_data.

Documentation Index #

Browse All Examples — Complete categorized index of all endpoint examples with chart previews.

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)

Moon Phase Endpoints #

Dedicated endpoints for detailed lunar phase analysis, using a simplified request model (no subject wrapper).

• Moon Phase (Example): Detailed moon phase for a specific date/time and location.
• Moon Phase Now (UTC) (Example): Current moon phase at Greenwich.
• Moon Phase Context (Example): Moon phase with AI-optimized XML context.
• Moon Phase Now Context (UTC) (Example): Current moon phase with AI-optimized XML context.

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 XML 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)

---

Powered by Kerykeion – the open-source Python astrology library.