RoxyAPI

Menu

  1. Docs
  3. Domain Guides
  5. Western Astrology

Western Astrology

A birth chart maps where the planets were when you were born. It is the foundation of horoscopes, compatibility reports, and personality profiles. Your users care about this for dating apps, daily guidance, and self-discovery features.

What you can build

  • Dating apps — compatibility scoring between two birth charts (synastry)
  • Daily horoscope widgets — transit-based forecasts for each zodiac sign
  • Birth chart readers — full natal chart with planets, houses, and aspects
  • Personality profiles — sun sign, moon sign, rising sign breakdowns

Which endpoints to call

Before you start

The code examples on this page use JavaScript's fetch() function. fetch() is the built-in way JavaScript talks to APIs over the internet — you give it a URL, it sends a request and brings back the response. It works in browsers, Node.js (18+), Bun, and Deno.

If you do not have a JavaScript runtime installed yet:

  • Node.js: Download from nodejs.org (LTS version). After installing, you can run .js files with node yourfile.js.
  • Bun: Faster alternative. Install from bun.sh. Run files with bun yourfile.js.
  • Browser: No install needed. Paste code into your browser's developer console (F12 → Console tab).
  • Python developer? The same API works with requests or httpx. See the Quickstart for a curl example you can adapt to any language.

Daily horoscope

One call, no birth data needed. Returns today's forecast for any zodiac sign.

This is the first code example in these guides, so every line is annotated. If you already know how fetch() works, skip the comments:

// fetch() sends an HTTP request to a URL and returns the response
const response = await fetch('https://roxyapi.com/api/v2/astrology/horoscope/aries/daily', {
  // no method needed — defaults to GET (just retrieving data, not sending any)
  headers: {
    // your API key — authenticates the request (like showing ID at a door)
    'X-API-Key': 'YOUR_API_KEY'
  }
});

// parse the JSON response into a JavaScript object you can use
const horoscope = await response.json();

// now use any field from the response:
console.log(horoscope.overview);        // "Saturn in Aries demands focus..."
console.log(horoscope.love);            // "Venus blesses Aries with charm..."
console.log(horoscope.luckyNumber);     // 16

What is await? API calls take time (your code sends a request over the internet and waits for a response). await pauses until the response arrives. You can only use it inside an async function. If you are not sure what that means, the Quickstart explains it with a full working example.

Response:

{
  "sign": "Aries",
  "date": "2026-03-15",
  "overview": "Saturn in Aries demands focus and discipline today.",
  "love": "Venus blesses Aries with charm and attraction today!",
  "career": "Take responsibility seriously. Hard work brings lasting results.",
  "health": "Maintain healthy routines. Listen to what your body needs.",
  "finance": "Financial luck favors you. Good day for purchases.",
  "advice": "Stay present and trust your intuition.",
  "luckyNumber": 16,
  "luckyColor": "Red",
  "compatibleSigns": ["Gemini", "Leo", "Libra"]
}

Which fields to show your users: overview is the main horoscope text. love, career, health, finance are category breakdowns. luckyNumber, luckyColor, and compatibleSigns are engagement features users love.

Birth chart (natal chart)

Requires birth date (ISO string), time (24h format), and location. This is a POST request because you are sending data to the server:

const response = await fetch('https://roxyapi.com/api/v2/astrology/natal-chart', {
  // POST means "send data to the server" (vs GET which just retrieves)
  method: 'POST',
  headers: {
    // tells the server the data below is in JSON format
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  // the data you are sending, converted from a JS object to a JSON string
  body: JSON.stringify({
    date: '1990-07-15',       // birth date in YYYY-MM-DD format
    time: '14:30:00',         // birth time in 24-hour HH:MM:SS format
    latitude: 40.7128,        // birth location latitude (New York City)
    longitude: -74.006,       // birth location longitude
    timezone: -4              // UTC offset (Eastern Daylight Time = -4)
  })
});
const chart = await response.json();

Which fields to show your users:

{
  "planets": [
    {
      "name": "Sun",            // show this: "Your Sun Sign"
      "sign": "Cancer",         // show this: the zodiac sign
      "house": 4,               // optional: advanced users care about house placement
      "degree": 22.45,          // skip: only for professional astrologers
      "isRetrograde": false     // skip unless building a detailed chart
    }
  ],
  "houses": [...],              // 12 life areas — show for advanced chart views
  "aspects": [...]              // planet relationships — show for detailed readings
}

The Sun sign, Moon sign, and Ascendant (rising sign) are the "big three" — the three most important placements. For a dating app, you only need name and sign from each planet. Find Sun, Moon, and the Ascendant in the planets array, and you have a personality profile.

Compatibility score

Send two sets of birth data. Returns an overall score (0-100) with category breakdowns:

const response = await fetch('https://roxyapi.com/api/v2/astrology/compatibility-score', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    person1: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -4 },
    person2: { date: '1992-03-22', time: '09:00:00', latitude: 34.0522, longitude: -118.2437, timezone: -7 }
  })
});
const compat = await response.json();
// compat.overall (0-100), compat.categories.romantic, compat.strengths, compat.challenges

Which fields to show your users: overall is the headline score (0-100). categories breaks it down into romantic, emotional, intellectual, physical, and spiritual scores. strengths and challenges are arrays of relationship dynamics. summary is a ready-made one-liner.

Synastry (detailed compatibility)

For apps that need deeper relationship analysis than a simple score:

const response = await fetch('https://roxyapi.com/api/v2/astrology/synastry', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    person1: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -4 },
    person2: { date: '1992-03-22', time: '09:00:00', latitude: 34.0522, longitude: -118.2437, timezone: -7 }
  })
});
const synastry = await response.json();
// synastry.aspects (inter-chart aspects), synastry.compatibilityScore

Key concepts

  • Sun sign — the zodiac sign the Sun was in at birth. What most people mean by "your sign."
  • Moon sign — emotional nature. The zodiac sign the Moon occupied.
  • Rising sign (Ascendant) — how others perceive you. Determined by the exact birth time and location.
  • Houses — 12 life areas (career, relationships, health). Calculated from birth time and location.
  • Aspects — angles between planets. Conjunctions, squares, and trines create personality dynamics.
  • Transits — where planets are today vs. your birth chart. Powers daily horoscopes.

You do not need to understand any of this to use the API. The responses include full interpretations in plain English.

Full API reference

See all Western Astrology endpoints, parameters, and response schemas in the API Reference.