Horoscope API Tutorial: Build a Daily Horoscope Feature

There are two kinds of “horoscope API”. One returns a block of text per zodiac sign. The other computes the actual sky for a person and tells you what’s really transiting their chart. This tutorial builds both with AstroWay, so you can pick the right one for your app.

The /horoscope/daily endpoint takes a sign and returns ready-to-render text. Weekly, monthly and yearly work the same way:

// TypeScript - npm install @astroway/sdk
import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const daily = await aw.horoscope.daily({ sign: 'leo', language: 'en' });
console.log(daily.text);

# Python - pip install astroway
from astroway import Astroway

aw = Astroway(api_key="aw_live_...")

daily = aw.horoscope.daily({"sign": "leo", "language": "en"})
print(daily.text)

Twelve calls (one per sign) gives you a full daily set to cache and serve to every user. Cheap, simple, and good enough for a widget or a newsletter.

Sign-based text is the same for a twelfth of the planet. If you want “your horoscope” - driven by the user’s own birth chart - compute their transits for the day. This is where a real ephemeris matters: the API returns the actual aspects forming, not a paragraph an LLM guessed.

const transits = await aw.transits.compute({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.45, longitude: 30.52,
  targetDate: '2027-01-01',
});

for (const hit of transits.aspects) {
  console.log(`${hit.transiting} ${hit.aspect} natal ${hit.natal}`);
}

Feed those aspects into your own copy templates, or into the AI interpretation endpoints for natural-language output with safety guardrails. Either way the underlying event (“Saturn square natal Sun, exact today”) is a calculation, not a hallucination - AI-only horoscope APIs routinely drift dates by days.

The cadence endpoints share the same shape - swap the method:

await aw.horoscope.daily({ sign: 'leo' });
await aw.horoscope.weekly({ sign: 'leo' });
await aw.horoscope.monthly({ sign: 'leo' });
await aw.horoscope.yearly({ sign: 'leo' });

For a “love horoscope” feature, /horoscope/compatibility takes two signs.

If you’re rendering into a chat or a typewriter UI, stream the AI horoscope instead of waiting for the full response:

for await (const chunk of aw.streamSSE('/horoscope/daily', { sign: 'leo' })) {
  process.stdout.write(chunk);
}

A sign-based horoscope is a few credits; transits cost more because they compute the sky. On the free tier (10,000 credits/month) you can generate and cache all twelve daily signs every day with plenty to spare. Cache sign-based text per (sign, date); only the transit-based, per-user path needs a live call.

• Horoscope API: endpoint reference
• Getting started: your first request in 5 minutes
• Natal chart API in Python: the chart behind the transits
• Pricing: credit costs per endpoint