Astrology API: The Complete Developer Guide #

An astrology API gives developers programmatic access to astrological calculations that would otherwise require deep domain expertise and months of engineering work. Instead of implementing Swiss Ephemeris bindings, house system formulas, and aspect geometry from scratch, you send a POST request with a birth date and location and get back planetary positions, house cusps, aspects, and even rendered chart images.

This guide covers everything you need to know about using an astrology API in your projects, from core concepts to working code in Python and JavaScript.

What Is an Astrology API? #

An astrology API is a REST service that performs astrological computations on demand. At minimum, it accepts a date, time, and geographic location, then returns calculated positions for celestial bodies using an astronomical ephemeris. More complete APIs also generate chart visualizations, compute relationship compatibility, and provide AI-driven interpretations.

The underlying math is non-trivial. Accurate planetary positions require the Swiss Ephemeris (a high-precision astronomical library), timezone-aware datetime handling, geodetic coordinate systems, and house system formulas that date back centuries. An astrology API abstracts all of this behind a simple HTTP interface.

Why Use an API Instead of Building From Scratch? #

Building astrological calculation software from the ground up means:

• Ephemeris integration: Binding to the Swiss Ephemeris C library or a wrapper, handling ephemeris data files, and dealing with platform-specific compilation.
• House system math: Implementing Placidus, Koch, Whole Sign, Equal, and other house systems, each with its own formula and edge cases (especially at extreme latitudes).
• Aspect calculation: Computing angular relationships between planets with configurable orbs, then classifying them as conjunctions, oppositions, trines, squares, sextiles, and minor aspects.
• Chart rendering: Generating SVG or canvas-based wheel charts with accurate degree placement, aspect lines, and readable labels.
• Timezone and DST handling: Resolving historical timezone transitions correctly for any date and location worldwide.

An API eliminates this entire stack. You write HTTP calls instead of astronomy code.

The Astrologer API: A Complete Astrological Backend #

The Astrologer API is a REST API available on RapidAPI that provides four categories of endpoints covering the full spectrum of astrological computation.

Base URL and Authentication #

All endpoints use the base URL:

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

Every request requires two headers for authentication via RapidAPI:

Get your API key on RapidAPI to start making requests.

Endpoint Categories #

1. Data Endpoints #

Data endpoints return raw calculated values in JSON. These are the building blocks for any astrology application.

• Subject – Calculates planetary positions, house cusps, and axes for a single birth moment.
• Now Subject – Same calculations for the current UTC moment.
• Compatibility Score – Numerical relationship score between two subjects with aspect breakdown.
• Chart Data endpoints (Natal, Synastry, Composite, Transit, Solar Return, Lunar Return) – Full chart computation with aspects, element/quality distributions, and more.

2. Chart Endpoints (SVG Rendering) #

Chart endpoints return ready-to-display SVG images alongside the computed data.

• Natal Chart – Classic birth chart wheel.
• Synastry Chart – Bi-wheel overlay of two charts.
• Composite Chart – Midpoint-derived relationship chart.
• Transit Chart – Natal chart with current transits overlaid.
• Solar Return Chart and Lunar Return Chart – Return charts for forecasting.
• Now Chart – Real-time sky chart.

3. Context Endpoints (AI Interpretations) #

Context endpoints produce XML-structured astrological interpretations optimized for LLMs. They combine the raw data with generative AI to create human-readable analysis.

• Subject Context – Interpretation of a single subject’s planetary placements.
• Natal Context – Full birth chart reading including aspects, houses, and element distribution.
• Synastry Context – Relationship dynamics between two people.
• Composite Context – Interpretation of a composite relationship chart.
• Transit Context – Current astrological influences on a natal chart.
• Solar Return and Lunar Return Context – Yearly and monthly forecasts.

4. Moon Phase Endpoint #

The Moon Phase endpoint returns detailed lunar data including phase name, illumination percentage, zodiac sign, upcoming phase dates, and eclipse information.

Quick Start: Your First API Call #

Here is how to fetch a subject’s astrological data in both Python and JavaScript.

Python #

import requests

url = "https://astrologer.p.rapidapi.com/api/v5/subject"

headers = {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "astrologer.p.rapidapi.com"
}

payload = {
    "subject": {
        "name": "John Doe",
        "year": 1990,
        "month": 1,
        "day": 1,
        "hour": 12,
        "minute": 30,
        "city": "London",
        "nation": "GB",
        "longitude": -0.1278,
        "latitude": 51.5074,
        "timezone": "Europe/London"
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

subject = data["subject"]
print(f"Sun: {subject['sun']['sign']} at {subject['sun']['position']:.2f} degrees")
print(f"Moon: {subject['moon']['sign']} at {subject['moon']['position']:.2f} degrees")
print(f"Ascendant: {subject['ascendant']['sign']}")

Output:

Sun: Cap at 10.84 degrees
Moon: Pis at 3.55 degrees
Ascendant: Ari

JavaScript (Node.js) #

const url = "https://astrologer.p.rapidapi.com/api/v5/subject";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "astrologer.p.rapidapi.com"
  },
  body: JSON.stringify({
    subject: {
      name: "John Doe",
      year: 1990,
      month: 1,
      day: 1,
      hour: 12,
      minute: 30,
      city: "London",
      nation: "GB",
      longitude: -0.1278,
      latitude: 51.5074,
      timezone: "Europe/London"
    }
  })
});

const data = await response.json();

const { sun, moon, ascendant } = data.subject;
console.log(`Sun: ${sun.sign} at ${sun.position.toFixed(2)} degrees`);
console.log(`Moon: ${moon.sign} at ${moon.position.toFixed(2)} degrees`);
console.log(`Ascendant: ${ascendant.sign}`);

Understanding the Subject Object #

The subject object is the fundamental input across all endpoints. It represents a person or event defined by a moment in time and a place on Earth.

You can provide coordinates directly or supply a geonames_username to let the API resolve location automatically from the city and country.

Common Use Cases #

Natal Chart Apps #

Generate birth charts with a single API call. Use the natal chart endpoint to get an SVG wheel chart and full planetary data in one response.

Compatibility and Matchmaking #

Combine the compatibility score endpoint for numerical scores with the synastry context for AI-generated relationship readings.

Horoscope Generators #

Use the transit context endpoint to get AI-optimized XML describing current planetary influences on a natal chart. Feed this to your own LLM to generate personalized horoscopes.

Moon Phase Trackers #

The moon phase endpoint provides everything needed for lunar calendars: phase name, illumination, zodiac sign, upcoming phase dates, and eclipse data.

Solar and Lunar Return Reports #

Generate yearly forecasts with solar return and monthly snapshots with lunar return endpoints.

Fetching an SVG Chart #

The chart endpoints return both the SVG markup and the underlying computed data. Here is an example that fetches a natal chart SVG.

Python #

import requests

url = "https://astrologer.p.rapidapi.com/api/v5/chart/birth-chart"

headers = {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "astrologer.p.rapidapi.com"
}

payload = {
    "subject": {
        "name": "John Doe",
        "year": 1990,
        "month": 1,
        "day": 1,
        "hour": 12,
        "minute": 30,
        "city": "London",
        "nation": "GB",
        "longitude": -0.1278,
        "latitude": 51.5074,
        "timezone": "Europe/London"
    },
    "theme": "classic"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

# Save the SVG to a file
with open("natal_chart.svg", "w") as f:
    f.write(data["chart"])

# Access the computed data
chart_data = data["chart_data"]
print(f"Chart type: {chart_data['chart_type']}")
print(f"House system: {chart_data['subject']['houses_system_name']}")

JavaScript (Browser) #

async function renderNatalChart(container) {
  const response = await fetch(
    "https://astrologer.p.rapidapi.com/api/v5/chart/birth-chart",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-RapidAPI-Key": "YOUR_API_KEY",
        "X-RapidAPI-Host": "astrologer.p.rapidapi.com"
      },
      body: JSON.stringify({
        subject: {
          name: "John Doe",
          year: 1990,
          month: 1,
          day: 1,
          hour: 12,
          minute: 30,
          city: "London",
          nation: "GB",
          longitude: -0.1278,
          latitude: 51.5074,
          timezone: "Europe/London"
        },
        theme: "classic"
      })
    }
  );

  const data = await response.json();

  // Render the SVG directly in the DOM
  container.innerHTML = data.chart;

  // Log aspect count
  const aspects = data.chart_data.aspects;
  console.log(`Found ${aspects.length} aspects`);
}

Configuring House Systems and Zodiac Types #

The API supports multiple house systems via the houses_system_identifier field:

For Sidereal calculations, set zodiac_type to "Sidereal" and provide a sidereal_mode such as "LAHIRI", "FAGAN_BRADLEY", or "RAMAN".

Next Steps #

• Get your API key on RapidAPI
• Read the full Astrologer API documentation
• Follow the Birth Chart API Tutorial for a deep dive into natal chart generation
• Learn how to build a horoscope generator with transit data and AI context
• See the end-to-end guide to building an astrology app