Astrology forecast API guide

Ship a daily transit tracker, a long-range significant-dates planner, a multi-domain digest, or a solar-return reading. One key, all events.

The Forecast domain is the multi-domain timeline engine of the RoxyAPI catalog. Five endpoints that turn one user birth data into a stream of dated events spanning Western transits, sign ingresses, retrograde stations, eclipses, Vedic dasha changes, and biorhythm critical days. Built on the Roxy Ephemeris, verified against NASA JPL Horizons.

What you can build

Personal weekly and monthly transit calendars
"Significant dates this year" widgets ranked by significance
Multi-domain daily digests (Western + Vedic + biorhythm in one feed)
Solar return charts for the annual birthday reading
Push-notification engines (precompute events for next 30 days, schedule local notifications)
Practitioner forecasting dashboards (filter by domain, weight Vedic over Western, etc.)

Prerequisites

A RoxyAPI key. Get your API key.
Birth date (YYYY-MM-DD), time (HH:MM:SS), and timezone. Latitude and longitude are optional for timeline endpoints and default to 0 (they do not affect transits). Required for solar return location.
For city -> lat/lng/timezone use GET /location/search.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

Call the endpoint

The #1 forecast call is the timeline. One POST with birthData and optional startDate / endDate, returns every significant event between those dates across all three forecast domains. Verified operationId: generateTimeline.

curl -X POST https://roxyapi.com/api/v2/forecast/timeline \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "birthData": {
      "date": "1990-07-15",
      "time": "14:30:00",
      "timezone": "America/New_York"
    },
    "startDate": "2026-05-01",
    "endDate": "2026-06-30"
  }'

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: timeline } = await roxy.forecast.generateTimeline({
  body: {
    birthData: { date: '1990-07-15', time: '14:30:00', timezone: 'America/New_York' },
    startDate: '2026-05-01',
    endDate: '2026-06-30',
  },
});

console.log(timeline.count, 'events');
for (const ev of timeline.events) {
  console.log(ev.date, ev.domain, ev.type, ev.description, ev.significance);
}

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

timeline = roxy.forecast.generate_timeline(
    birth_data={'date': '1990-07-15', 'time': '14:30:00', 'timezone': 'America/New_York'},
    start_date='2026-05-01',
    end_date='2026-06-30',
)
print(timeline['count'], 'events')
for ev in timeline['events']:
    print(ev['date'], ev['domain'], ev['type'], ev['description'])

<?php

use function RoxyAPI\Sdk\createRoxy;

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

$timeline = $roxy->forecast->generateTimeline(
    birthData: ['date' => '1990-07-15', 'time' => '14:30:00', 'timezone' => 'America/New_York'],
    startDate: '2026-05-01',
    endDate: '2026-06-30',
);
echo $timeline['count'], ' events';

using RoxyApi;
using Microsoft.Kiota.Abstractions; // for the Date and Time types

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

var timeline = await roxy.Forecast.Timeline.PostAsync(new()
{
    BirthData = new()
    {
        Date = new Date(1990, 7, 15),
        Time = new Time(14, 30, 0),
        Timezone = new() { String = "America/New_York" },
    },
    StartDate = new Date(2026, 5, 1),
    EndDate = new Date(2026, 6, 30),
});

Console.WriteLine($"{timeline!.Count} events");
foreach (var ev in timeline.Events!)
    Console.WriteLine($"{ev.Date} {ev.Domain} {ev.Type} {ev.Description} {ev.Significance}");

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

Then in any MCP client: "what major astrological events do I have between May and June for someone born July 15 1990 at 2:30 PM in New York?" Full setup for Cursor, Claude Desktop, Antigravity, and other clients: MCP guide.

Response top-level: birthData, startDate, endDate, count, events[]. Each event has date, datetime (ISO-8601 UTC), domain (western | vedic | biorhythm), type (transit-aspect, sign-ingress, retrograde-station, eclipse, dasha-change, critical-day), body, target, aspect, orb, description, significance (0 to 100), kind, station, obscuration, phase.

Render the result

Option A: drop-in web component

<roxy-forecast-timeline> from @roxyapi/ui renders the events as a chronological list grouped by date, color-coded by domain, with significance bars.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js" defer></script>
<roxy-forecast-timeline id="t"></roxy-forecast-timeline>
<script type="module">
  document.getElementById('t').data = timelineResponse;
</script>

Framework-agnostic, themeable via CSS custom properties.

Option B: build your own list

timeline.events
  .filter(ev => ev.significance >= 50)
  .map(ev => `${ev.date}  ${ev.domain.padEnd(10)} ${ev.description}`);

Ship the rest

Significant dates over a long window

POST /forecast/significant-dates (findSignificantDates) selects high-significance events within a date window. It accepts domains[] and domainWeights so an app can give one domain more weight, and minSignificance filters out background noise. The API clamps the end date to its supported window; use the returned startDate and endDate as the actual bounds.

Multi-domain daily digest

POST /forecast/digest (generateDigest) groups events into windows (typically a day or a week each). Use it for "today summary" or "this week summary" UIs. Returns windows[] with grouped events plus a per-window highlight.

Daily transit-only

POST /forecast/transits (forecastTransits) is timeline narrowed to the Western transit-aspect and retrograde-station types. Lighter payload when you only need transits.

Solar return

POST /forecast/solar-return (forecastSolarReturn) takes flat date, time, year, latitude, longitude and timezone fields, all required, plus optional houseSystem. It does not take a nested birth or birthData object. Returns the solar-return chart, natal Sun position, the exact solar-return date, and the location used. Use the location fields for the chart location and ensure the timezone correctly interprets the supplied birth time.

Choose events and display them clearly

Let readers select a date window and domains before generating a calendar. Use the stable domain and type values for filters; localize the displayed descriptions separately. Group events chronologically and convert the UTC datetime into the reader display timezone, so an event near midnight appears on the correct local day.

Treat significance as a ranking within the forecast model. It is not a probability of an event happening or a measure of medical or financial risk. domainWeights changes which events survive selection; explain that preference rather than presenting the resulting rank as universal importance. Biorhythm critical days describe a symbolic cycle model and do not predict health, safety or physical performance.

For reminders, prefetch the supported window on your backend and schedule only events the reader opts into. Keep cached personal forecasts private and scoped to the user, full birth inputs, requested dates, domain options, language and calculation version. Refresh when those inputs change, and disclose the selected display timezone before enabling notifications.

See the full Forecast domain at the API Reference.

Ready-made template

There is no Forecast-only template yet. The astrology-ai-chatbot template covers Forecast via Remote MCP alongside the other 17 domains. Browse at /templates/astrology-ai-chatbot. For a custom forecast dashboard, the personalized tracker tutorial wires generateTimeline into a full daily UI.

Gotchas

Timeline endpoints use nested birthData. { birthData: { date, time, timezone, ... } }. Solar return instead uses flat fields.
timezone is required inside birthData. Latitude and longitude default to 0 and do not affect the timeline (transits are calculated from natal positions, not birth location). Pass real coordinates for solar return.
domain and type are stable machine values, never localized. Branch on them under any language.
significance runs 0 to 100, the same scale minSignificance filters on.
startDate and endDate are optional. Default window is server-defined (typically 30 days from today). Pin them when you need exact bounds.
IANA timezone DST-resolves against the birth date. "America/New_York" becomes EST or EDT automatically.
Lunar eclipse events include obscuration (fraction of the Moon covered by the Earth umbra, 0 to 1). Retrograde stations include station (direct or retrograde). Sign ingresses include body (the planet) and target (the sign).
Dasha body labels are fixed English strings, outermost lord first: Saturn Mahadasha, Saturn-Mercury Antardasha, Saturn-Mercury-Ketu Pratyantardasha. Split on the space, then on the hyphens. datetime is the boundary to the second, counted from the birth instant.
Positions read directly from the NASA JPL DE440 ephemeris, verified against NASA JPL Horizons. Same Roxy Ephemeris that powers Western, Vedic, and Human Design.

What to build next

The personalized tracker tutorial combines generateTimeline with generateBodygraph and calculateLifePath for a single-user daily dashboard.
The Human Design guide covers the daily HD transit endpoint that pairs with the forecast feed.
The vedic guide covers Vimshottari dasha (whose dasha-change events appear in the forecast feed).
The AI chatbot tutorial shows the forecast tool registration for natural-language queries.