# 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

1. A Roxy API key from [/account](/account).
2. 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.
3. For city -> lat/lng/timezone use [`GET /location/search`](/api-reference#tag/location/GET/location/search).

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
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
```bash
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"
  }'
```

### TypeScript SDK
```typescript
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);
}
```

### Python SDK
```python
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 SDK
```php
<?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';
```

### MCP
```bash
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`](/docs/ui) renders the events as a chronological list grouped by date, color-coded by domain, with significance bars.

```html
<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

```typescript
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`](/api-reference#tag/forecast/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`](/api-reference#tag/forecast/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`](/api-reference#tag/forecast/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`](/api-reference#tag/forecast/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](/api-reference#tag/forecast).

## Ready-made starter

There is no Forecast-only starter yet. The [astrology-ai-chatbot starter](https://github.com/RoxyAPI/astrology-ai-chatbot) covers Forecast via Remote MCP alongside the other 11 domains. Browse at [/starters/astrology-ai-chatbot](/starters). For a custom forecast dashboard, the [personalized tracker tutorial](/docs/tutorials/personalized-tracker) 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](/docs/tutorials/personalized-tracker) combines `generateTimeline` with `generateBodygraph` and `calculateLifePath` for a single-user daily dashboard.
- The [Human Design guide](/docs/guides/human-design) covers the daily HD transit endpoint that pairs with the forecast feed.
- The [vedic guide](/docs/guides/vedic-astrology) covers Vimshottari dasha (whose `dasha-change` events appear in the forecast feed).
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows the forecast tool registration for natural-language queries.