Forecast API, what to build and how to call it

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

The Forecast domain is the May 2026 multi-domain timeline engine. 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 Roxy API key from /account.
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

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';

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?"

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-1), kind, station, obscuration.

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 >= 0.5)
  .map(ev => `${ev.date}  ${ev.domain.padEnd(10)} ${ev.description}`);

Ship the rest

Significant dates over a long window

POST /forecast/significant-dates (findSignificantDates) is the timeline endpoint tuned for "what should I plan for in the next 6 to 12 months?" It accepts domains[] and domainWeights so a Vedic-leaning app weights dasha changes higher than Western transits, and minSignificance filters out background noise.

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 birth data plus year and an optional relocation latitude / longitude / timezone for the annual birthday chart. Returns the solar-return chart, natal Sun position, the exact solar-return date, and the location used. Solar-return readings are a premium offering for practitioner apps.

See the full Forecast domain at the API Reference.

Ready-made starter

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

Gotchas

birthData is a nested object, not flat fields. { birthData: { date, time, timezone, ... } }. Easy to flatten by mistake.
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 is 0 to 1, not 0 to 100. Multiply by 100 for percentage display.
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.
Eclipse events include obscuration (fraction of solar disc covered, 0 to 1). Retrograde stations include station (direct or retrograde). Sign ingresses include body (the planet) and target (the sign).
Calculations 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.