RoxyAPI
Quick StartAGENTS.mdSDKMCP SetupFree StartersAPI Playground
  1. Docs
  3. Domain Guides
  5. Western Astrology

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

  • 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

Prerequisites

  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.

No key yet? The API Playground has a pre-filled test key. Make live calls from the browser before you pay.

Install

npm install @roxyapi/sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the 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"

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
}

Render the result

RoxyAPI ships an official drop-in component for the horoscope endpoints, so the render layer is one line. RoxyHoroscopeCard from @roxyapi/ui reads overview, the four categories, luckyNumber, luckyColor, compatibleSigns, and the energy rating straight off the response, so you pass the data and ship. Prefer your own markup? The response is plain JSON, render it however you like.

npm install @roxyapi/ui-react

The data flows the same way: your server route returns the unwrapped response, the client component renders it. Set period to daily, weekly, or monthly to match the endpoint you called.

'use client';
import { RoxyHoroscopeCard, type RoxyHoroscopeCardProps } from '@roxyapi/ui-react';
import { useState } from 'react';

export function DailyHoroscope() {
  const [data, setData] = useState<RoxyHoroscopeCardProps['data']>(undefined);

  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 <RoxyHoroscopeCard data={data} period="daily" />;
}

RoxyHoroscopeCardProps['data'] is the spec-derived response type from the component. Never declare a local interface for a Roxy response, it drifts the moment the spec changes. Your /api/horoscope route must return the unwrapped response, not the SDK envelope. The SDK gives you { data, error }, so destructure data and send that:

// app/api/horoscope/route.ts (server side, holds the key)
import { createRoxy } from '@roxyapi/sdk';

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

export async function GET(req: Request) {
  const sign = new URL(req.url).searchParams.get('sign') ?? 'aries';
  const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign } });
  return Response.json(data);
}

Never call Roxy directly from a browser. Anyone viewing page source sees your key. Put the fetch in a Next.js route, a Vercel function, or any backend you control. The component renders on the client, the key stays on the server. See the Next.js integration guide for the drop-in pattern.

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. Render it with RoxyNatalChart (the houseSystem prop selects the layout), or RoxyWesternPlanetsTable for a column view. Pass the unwrapped data, same as the horoscope card.

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"
  }'

Do not ask users to type coordinates. Call GET /location/search?q=New+York first, take latitude, longitude, and timezone from cities[0], feed them in. The city search returns the IANA identifier which resolves to the DST-correct offset for the birth date automatically.

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. Render it with RoxySynastryChart, a dual-wheel with the inter-aspects table built in.

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. Render it with RoxyCompatibilityCard, a score card with category breakdown.

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. Render it with RoxyMoonPhase, where the mode prop switches between the single-phase card and the calendar.

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.

Ready-made starter

The /starters/astrology-starter-app starter ships a working Western astrology app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, drop in <roxy-natal-chart> from @roxyapi/ui.

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.