Astrology API, what to build and how to call it

Ship a zodiac compatibility feature, a daily horoscope widget, or a full natal chart reader in under 30 minutes. No astrology knowledge required.

The astrology domain is the highest-volume domain in the Roxy catalog. Natal charts power dating apps and personality readers. Daily horoscopes drive DAU, push notifications, and streaks. Synastry is the premium dating-app bolt-on. Every response ships with plain English interpretation text, so you never have to write a word about planets.

What you can build with this

• Zodiac dating and compatibility apps, Co-Star style
• Daily horoscope widgets and wellness embeds
• Full birth chart readers with sun, moon, rising
• Moon phase widgets for cycle-tracking and meditation apps
• "What is happening for me today" transit forecasts

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page. The key is displayed and emailed the moment checkout completes.
2. Nothing else. All planetary math runs on our servers.

Step 1, call your first endpoint

The #1 astrology call is the daily horoscope. One GET, no birth data, takes a sign and returns the full forecast. Pick a language tab and paste.

curl https://roxyapi.com/api/v2/astrology/horoscope/aries/daily \
  -H "X-API-Key: $ROXY_API_KEY"

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

console.log(data.overview);    // main forecast
console.log(data.love);        // love and relationship outlook
console.log(data.luckyNumber); // e.g. 7

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

horoscope = roxy.astrology.get_daily_horoscope(sign='aries')
print(horoscope['overview'])
print(horoscope['love'])
print(horoscope['luckyNumber'])

claude mcp add-json --scope user roxy-astrology '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

The response looks like:

{
  "sign": "Aries",
  "date": "2026-04-23",
  "overview": "Saturn in Aries demands focus and discipline today.",
  "love": "Venus blesses Aries with charm and attraction.",
  "career": "Take responsibility seriously.",
  "health": "Maintain healthy routines.",
  "finance": "Financial luck favors you.",
  "advice": "Stay present and trust your intuition.",
  "luckyNumber": 16,
  "luckyColor": "Red",
  "compatibleSigns": ["Gemini", "Leo", "Libra"],
  "activeTransits": [],
  "moonSign": "Virgo",
  "moonPhase": "Waxing Crescent",
  "energyRating": 8
}

Step 2, render it to the user

Drop this in a React component. overview is the hero, the four categories are the breakdown cards, luckyNumber and luckyColor are engagement sparkle.

'use client';
import { useState } from 'react';

export function DailyHoroscope() {
  const [data, setData] = useState<any>(null);

  async function load(sign: string) {
    const res = await fetch(`/api/horoscope?sign=${sign}`); // your backend route
    setData(await res.json());
  }

  if (!data) return <button onClick={() => load('aries')}>Read the Aries forecast</button>;

  return (
    <article>
      <h2>{data.sign} for {data.date}</h2>
      <p>{data.overview}</p>
      <ul>
        <li><strong>Love.</strong> {data.love}</li>
        <li><strong>Career.</strong> {data.career}</li>
        <li><strong>Health.</strong> {data.health}</li>
        <li><strong>Finance.</strong> {data.finance}</li>
      </ul>
      <footer>Lucky number {data.luckyNumber}. Compatible with {data.compatibleSigns.join(', ')}.</footer>
    </article>
  );
}

Step 3, ship the rest

Four more endpoints cover every mainstream astrology feature. Same auth header, structure is identical.

Natal chart, the #1 birth-data call

POST /astrology/natal-chart returns planets, houses, aspects, ascendant, midheaven, plus an interpretation block on every planet tuned to its exact sign and house. This is what dating apps, personality readers, and Co-Star clones call first.

curl -X POST https://roxyapi.com/api/v2/astrology/natal-chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York"
  }'

Synastry, the dating-app pro tier

POST /astrology/synastry takes two people, returns a 0 to 100 compatibility score, inter-aspects, strengths, and challenges. Perfect for relationship features.

Compatibility score, the match-card one-liner

POST /astrology/compatibility-score returns the same percent plus a one-line archetype. Lighter than synastry, ideal for dating-app match cards.

Moon phase, zero-friction viral feature

GET /astrology/moon-phase/current needs no input. Returns phase name, illumination, sign, and a meaning block. Wellness, meditation, and cycle-tracking apps put this on the home screen.

curl https://roxyapi.com/api/v2/astrology/moon-phase/current \
  -H "X-API-Key: $ROXY_API_KEY"

See the full list at the API Reference, 23 endpoints in total including weekly and monthly horoscopes, transits with natal overlay, and the moon calendar.

Gotchas

• Timezone accepts decimal or IANA string. Pass -5 or "America/New_York". IANA is preferred because the server resolves it to the DST-correct offset for the birth date, so a January 1990 New York chart gets EST not EDT.
• Retrograde is per-planet, never global. The response has isRetrograde: true on individual planets. Never render "Mercury retrograde" as a global flag, check the specific planet.
• Timezone is required for natal, synastry, and compatibility-score. There is no default. Geocode the city, do not guess.
• The three big placements are Sun, Moon, Ascendant. For dating and personality apps you only need name and sign from those three entries in the planets array.
• Sign names are lowercase in URL paths. aries, not Aries. Server is case-insensitive but your logs will be cleaner if you normalize early.

What to build next

The daily horoscope widget tutorial turns the call above into a deployable HTML page in under 20 minutes. The dating compatibility app tutorial uses synastry for a working Next.js app. For the deeper engine, the SDK guide walks through typed calls across all domains.