> Documentation index: https://roxyapi.com/llms.txt. Building an integration? Read https://roxyapi.com/AGENTS.md first.

# 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](/docs/tutorials/horoscope-widget "horoscope HTML code for a daily 12-sign page"); every parameter and field is in the [API reference](/api-reference "RoxyAPI API reference and playground").

![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](/img/docs/horoscope-api-json.webp)

## 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

| Endpoint | Period | `column` length (English) | Adds |
|---|---|---|---|
| `GET /astrology/horoscope/{sign}/daily` | One day on your clock | 80 to 120 words | `moonSign`, `moonPhase`, `activeTransits`, `crystal` |
| `GET /astrology/horoscope/{sign}/weekly` | Monday to Sunday | 120 to 160 words | `luckyDays` |
| `GET /astrology/horoscope/{sign}/monthly` | The calendar month | 180 to 250 words | `keyDates`, `weekByWeek` |
| `GET /astrology/horoscope/{sign}/yearly` | The calendar year | 190 to 320 words | `eclipses`, `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](/account?tab=keys "create your RoxyAPI 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](https://ssd.jpl.nasa.gov/horizons/ "NASA JPL Horizons ephemeris service") or any almanac: the [methodology](/methodology "how RoxyAPI verifies its astronomy") shows how every position is verified.

| Field | What it holds |
|---|---|
| `events[].type` | `aspect`, `sign-ingress`, `retrograde-station`, `lunar-phase`, `eclipse` or `solar-season` |
| `events[].at` | The exact instant, to the second, on the clock you passed |
| `events[].bodies`, `events[].placements` | Who is involved, with each sign and house |
| `events[].house` | The house the event falls in for this sign, 1 to 12 |
| `events[].through` | When 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](/docs/tutorials/horoscope-widget "horoscope HTML code for a daily 12-sign page"), add charts and transits from the [astrology API guide](/docs/guides/astrology "astrology API guide"), and translate the rest of your app with [localization](/docs/guides/localization "multi-language astrology API").
