Skip to content
RoxyAPI
Get API Key

Horoscope API JSON backed by real transits

Daily, weekly, monthly and yearly horoscopes for all 12 signs, each composed from the real transits of its period and returned with the events and planet positions behind every line.

This page explains how a reading is made and what each part of the JSON means. To put a reading on a page, follow the horoscope HTML code tutorial; every parameter and field is in the API reference.

How a horoscope is made: the request, the sky computed from the NASA JPL ephemeris, events placed in the houses of the sign, the lead event setting focus, the column composed, and the response carrying column, events and positions

How a reading is made

  1. You ask for a sign, a period and a clock. sign in the path, date (or year for the yearly), timezone for the clock the period is read on, and lang.
  2. The sky of that period is computed from the NASA JPL DE440 ephemeris, verified against NASA JPL Horizons. It finds where the Sun, the Moon and every planet to Pluto stand, and every exact event: aspects, sign ingresses, retrograde stations, lunar phases and eclipses, each to the second.
  3. Each event lands in a house of the sign. Whole-sign houses counted from the sign you asked for turn one shared sky into twelve different readings: Venus in Taurus is the money house for Aries and the house of identity for Taurus.
  4. The lead event sets the reading. Its life area becomes focus, and the column opens on it.
  5. The column and six topic fields are composed from editorial copy written for each planet, aspect, house and life area, in each language. No language model writes a reading, so the same sign and period always return the same text, and a piece scheduled months ahead is the piece that runs.
  6. The response carries the prose and its evidence. events[] lists every event the reading is built on, positions[] where each body stands, so every date and claim in the text checks against the data in the same response.

Four periods, one shape

EndpointPeriodcolumn length (English)Adds
GET /astrology/horoscope/{sign}/dailyOne day on your clock80 to 120 wordsmoonSign, moonPhase, activeTransits, crystal
GET /astrology/horoscope/{sign}/weeklyMonday to Sunday120 to 160 wordsluckyDays
GET /astrology/horoscope/{sign}/monthlyThe calendar month180 to 250 wordskeyDates, weekByWeek
GET /astrology/horoscope/{sign}/yearlyThe calendar year190 to 320 wordseclipses, retrogrades, keyPeriods, bestPeriods, themes

Every period returns column, the complete piece ready to run, and the topic shape: overview, love, career, health, finance and advice. Render one shape, never both. Every period also returns focus, events, positions and compatibleSigns.

bash
curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily?date=2026-04-03" \
  -H "X-API-Key: YOUR_KEY"

No key yet? Get your API key.

Every line checks against the data

That call returns the Aries daily for 2026-04-03 on UTC, here trimmed to the line about Venus and the rows behind it:

json
{
  "sign": "Aries",
  "date": "2026-04-03",
  "focus": "finance",
  "column": "... Warmth without strings is the wish when sensual Venus in your zone of money and personal worth squares Pluto today: friction that pushes growth. ...",
  "events": [
    {
      "type": "aspect",
      "at": "2026-04-03T22:38:01Z",
      "bodies": ["Venus", "Pluto"],
      "placements": [
        { "name": "Venus", "sign": "taurus", "house": 2 },
        { "name": "Pluto", "sign": "aquarius", "house": 11 }
      ],
      "aspect": "square",
      "house": 2,
      "through": "2026-04-09T17:01:45Z"
    }
  ],
  "positions": [
    {
      "name": "Venus",
      "sign": "taurus",
      "house": 2,
      "isRetrograde": false,
      "dignity": "domicile",
      "enteredAt": "2026-03-30T16:00:52Z",
      "leavesAt": "2026-04-24T04:03:25Z"
    }
  ]
}

The column says Venus squares Pluto today from the money house. The event row gives the exact instant, both bodies, their signs and houses, and how long the square holds. Check any at against NASA JPL Horizons or any almanac: the methodology shows how every position is verified.

FieldWhat it holds
events[].typeaspect, sign-ingress, retrograde-station, lunar-phase, eclipse or solar-season
events[].atThe exact instant, to the second, on the clock you passed
events[].bodies, events[].placementsWho is involved, with each sign and house
events[].houseThe house the event falls in for this sign, 1 to 12
events[].throughWhen the window the event holds open closes, where that is a real fact
positions[]Each body with sign, house, isRetrograde, dignity, enteredAt, leavesAt, and turnsDirectAt while retrograde

Names, signs, aspects and types stay canonical English in every language, so your code can switch on them. Only the prose is translated.

Route your own content on focus

focus names the topic a reading is mainly about: love, career, finance or health when the lead event falls in that life area, overview for a bigger-picture period. It is canonical English in every language and matches the topic field that opens on the same lead.

  • finance: show a budgeting article beside the reading.
  • love: offer a compatibility check or a relationship reading.
  • career: link a career coaching session.
  • overview: feature the full column on its own.
js
const response = await fetch('https://roxyapi.com/api/v2/astrology/horoscope/aries/daily', {
  headers: { 'X-API-Key': process.env.ROXY_API_KEY },
});
const reading = await response.json();
const cta = { love: '/compatibility', career: '/coaching', finance: '/budget', health: '/wellness', overview: '/today' };
console.log(reading.focus, cta[reading.focus]);

Your reader, your clock, your language

  • timezone decides which events fall in the period, so a transit the evening before in New York is never called today, and every instant prints on that clock. It takes an IANA name (America/New_York), decimal hours (5.5) or an offset (-05:00), and defaults to UTC.
  • date schedules or backfills any period, past or future; the yearly takes year.
  • lang composes the reading natively in English, German, Spanish, French, Hindi, Portuguese, Russian, and Turkish. Positions are the same in every language, and events lists the events the reading in that language names.

FAQ

Does a language model write these horoscopes?

No. Every reading is composed from the transits of its period and editorial copy written for each planet, aspect, house and life area. The same sign and period always return the same text, so you can review a piece before it runs.

How do I check a horoscope against the real sky?

Every event the reading names is a row of events[] with its exact instant, bodies, signs and house, and positions[] gives where each body stands. Compare any instant with NASA JPL Horizons or a printed almanac.

Why do two signs get different horoscopes on the same day?

Each event is read into the whole-sign houses of the sign you ask for. The same Venus square lands in the money house for one sign and the house of partnership for another, so the life area, the focus and the column all differ.

What is the focus field for?

focus names the topic the reading leads with: love, career, finance, health or overview. It stays in English in every language, so you can route a call to action, a product or an article on it without parsing the text.

Can I schedule horoscopes ahead or show past ones?

Yes. Pass date for any day, week or month, or year for the yearly, in the past or the future, and choose the clock with timezone.

Next steps

Render a 12-sign page with the horoscope HTML code tutorial, add charts and transits from the astrology API guide, and translate the rest of your app with localization.