Astrology API guide

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 RoxyAPI 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 RoxyAPI key. Get your API key. The key is created the moment checkout completes, and the welcome email carries a one-time link that shows it.
2. Nothing else. All planetary math runs on our servers.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package 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"

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'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$horoscope = $roxy->astrology->getDailyHoroscope(sign: 'aries');
echo $horoscope['overview'];
echo $horoscope['love'];
echo $horoscope['luckyNumber'];

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var horoscope = await roxy.Astrology.Horoscope["aries"].Daily.GetAsync();

Console.WriteLine(horoscope!.Overview);    // main forecast
Console.WriteLine(horoscope.Love);         // love and relationship outlook
Console.WriteLine(horoscope.LuckyNumber);  // e.g. 7

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": "The Sun makes a semi-sextile with Neptune today, reaching your second house, where earnings and belongings get counted, and their worth gets decided. Held against the fact that a price gets put on things that were never priced before, the part that wants to be seen looks smaller and more useful.",
  "love": "The Moon enters Leo today, and it registers in your fifth house of romance, creativity, and joy. Since something gets made or enjoyed for its own sake, with no return required, the first reaction gets tested rather than admired. Nothing else in your fifth house works without an hour spent on something with no useful outcome.",
  "career": "Mercury pours into Aries in your first house, where the body and the manner arrive together and get taken as one thing, and its stock there is talk, paperwork, short journeys, and anything that has to be explained. Saturn berths in Aries, in your first house, where a person is read off how they carry themselves rather than off what they claim, and it keeps wanting fewer promises and better ones. Audit the promise made earlier against what has actually been delivered.",
  "health": "The first house you keep identity and self-expression in takes this one, since the Sun forms a semi-sextile to Neptune today. Between the center of the matter and the blurred edge, the difference is the whole story. Where the body and the manner arrive together and get taken as one thing, the will is either the tool or the obstacle. Your first house asks for one honest sentence about where things stand.",
  "finance": "Your second house carries this one, because the Sun makes a semi-sextile with Neptune today. The will does not survive contact with the blurred edge unchanged. Since earnings and belongings get counted, and their worth gets decided, the center of the matter gets tested rather than admired. The useful move is toward a decision about worth made while nothing is urgent.",
  "advice": "The Sun forms a semi-sextile to Neptune today, arriving in your second house of finances and personal values. Doing that comes to the number written down before it is spent.",
  "column": "The Sun makes a semi-sextile with Neptune today. That is the fact your second house is working with. Part of this is the center of the matter and part of it is the longing with no object. Work with the fact that earnings and belongings get counted, and their worth gets decided, and the will stops fighting the room. In the same stretch, the Moon enters Leo today, pressing the need underneath the argument against your fifth house of romance, creativity, and joy, where something gets made or enjoyed for its own sake, with no return required. Since a thing is done because it is wanted, not because it pays, the first reaction gets tested rather than admired. Start with an hour spent on something with no useful outcome. Let the rest sit, and put the effort into an honest figure rather than a comfortable one.",
  "events": [
    {
      "type": "aspect",
      "at": "2026-04-23T03:32:30Z",
      "bodies": [
        "Sun",
        "Neptune"
      ],
      "aspect": "semi-sextile",
      "house": 2,
      "through": "2026-04-26T08:04:33Z"
    },
    {
      "type": "sign-ingress",
      "at": "2026-04-23T19:40:39Z",
      "bodies": [
        "Moon"
      ],
      "sign": "leo",
      "house": 5,
      "through": "2026-04-26T01:04:22Z"
    }
  ],
  "luckyNumber": 9,
  "luckyColor": "Red",
  "compatibleSigns": [
    "Leo",
    "Sagittarius",
    "Gemini"
  ],
  "activeTransits": [
    "Sun in Taurus (your second house of finances and personal values)",
    "Moon in Cancer (your fourth house of home and emotional foundations)",
    "Mercury in Aries (your first house of identity and self-expression)",
    "Venus in Taurus (your second house of finances and personal values)",
    "Mars in Aries (your first house of identity and self-expression)",
    "Jupiter in Cancer (your fourth house of home and emotional foundations)",
    "Saturn in Aries (your first house of identity and self-expression)"
  ],
  "moonSign": "Cancer",
  "moonPhase": "Waxing Crescent Moon",
  "energyRating": 7
}

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 RoxyAPI 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);
}

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

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, 39 endpoints in total including weekly, monthly and yearly horoscopes, transits with natal overlay, monthly aspect and declination calendars, node passages, and the moon calendar.

Ready-made template

The /templates/astrology-starter-app template 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.
• Validating against desktop software? Cast both charts at the same coordinates. Positions are apparent geocentric on the true ecliptic of date (light time and aberration applied, nutation included), the convention chart programs and the NASA JPL Horizons observer tables print, so planets compare directly. The Ascendant, Midheaven and every house cusp sit on the same frame and agree with the reference to the arcsecond, but they move with the birthplace: a reference that casts at a town position rounded to whole arcminutes shifts the angles and cusps by several arcminutes, unevenly across the twelve, while the planets stay put. Pass the coordinates the reference used and the charts line up. birthDetails echoes the coordinates every chart was cast at.
• 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.