# 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](/pricing). The key is displayed and emailed the moment checkout completes.
2. Nothing else. All planetary math runs on our servers.

**Tip: No key yet? The [API Playground](/api-reference) has a pre-filled test key. Make live calls from the browser before you pay.**

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## 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
```bash
curl https://roxyapi.com/api/v2/astrology/horoscope/aries/daily \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK
```typescript
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
```

### Python SDK
```python
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 SDK
```php
<?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'];
```

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

Then ask Claude, "give me the Aries horoscope for today." The agent picks the right tool, fills in the sign, calls the API. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

The response looks like:

```json
{
  "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](/docs/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.

```bash
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.

```tsx
'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:

```ts
// 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);
}
```

**Warning: 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](/docs/integrations/nextjs) 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`](/api-reference#tag/western-astrology/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.

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

**Tip: 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`](/api-reference#tag/western-astrology/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`](/api-reference#tag/western-astrology/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`](/api-reference#tag/western-astrology/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.

```bash
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](/api-reference#tag/western-astrology), 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](/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](/docs/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](/docs/tutorials/horoscope-widget) turns the call above into a deployable HTML page in under 20 minutes. The [dating compatibility app tutorial](/docs/tutorials/dating-app) uses synastry for a working Next.js app. For the deeper engine, the [SDK guide](/docs/sdk) walks through typed calls across all domains.