# Forecast API

> Merge upcoming transit aspects, sign ingresses, retrograde stations, Vimshottari dasha changes, and biorhythm critical days into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over remote MCP with typed SDKs. Horizon capped at 90 days.

Ship a cross-domain forecast your users can plan around. This week.

- Product page: https://roxyapi.com/products/forecast-api
- OpenAPI spec: https://roxyapi.com/api/v2/forecast/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/forecast
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <200ms
- uptime: 99.9%
- endpoints: 3

## Features

- One merged timeline across three engines: western transit-to-natal aspects, sign ingresses, and retrograde stations, vedic Vimshottari mahadasha and antardasha boundaries, and biorhythm critical days
- Single subject per request and one forecast per response, a stateless bounded forecast rather than an open-ended batch scan
- Server-clamped 90 day horizon and a 200 event cap, with the highest-significance events surviving the cap
- Every astronomical event refined to its exact instant by search, not reported at a coarse daily sample point
- Significance scoring from 0 to 100 so outer-planet exact aspects and mahadasha changes rank above fast Moon events and critical days
- Selectable domains: request the full cross-domain merge, a western-only transit forecast, or just the high-significance dates

## Use Cases

- Spiritual and self-discovery apps: a forward-looking what is coming digest that blends astrology and biorhythm in one call
- AI chatbots and coaching assistants: significant-date awareness via remote MCP tool calls for timing conversations
- Wellness and mindfulness platforms: critical-day and transit alerts for planning demanding or restful periods
- Calendar and planner integrations: a time-ordered event stream ready to drop onto a date strip or notification feed
- Astrology and Vedic practitioner tools: upcoming transits, stations, and dasha boundaries for one client at a time
- Content and editorial platforms: significant upcoming dates for forecast columns and personalized timing pages

## Endpoints

- `POST /api/v2/forecast/timeline` Cross-domain forecast timeline - Transits, ingresses, stations, dasha changes, critical days
- `POST /api/v2/forecast/transits` Western transit forecast - Transit aspects, sign ingresses, retrograde stations
- `POST /api/v2/forecast/significant-dates` Significant dates - High-significance cross-domain forecast highlights

## Example Response

```
POST /api/v2/forecast/timeline
```

```json
{
  "startDate": "2026-06-01",
  "endDate": "2026-08-30",
  "count": 3,
  "events": [
    {
      "date": "2026-06-09",
      "datetime": "2026-06-09T11:02:44Z",
      "domain": "western",
      "type": "retrograde-station",
      "body": "Saturn",
      "station": "retrograde",
      "description": "Saturn stations retrograde, beginning a review phase in its themes.",
      "significance": 80
    },
    {
      "date": "2026-07-04",
      "datetime": "2026-07-04T08:42:11Z",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Saturn",
      "target": "Moon",
      "aspect": "square",
      "orb": 0.12,
      "description": "Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.",
      "significance": 90
    },
    {
      "date": "2026-08-21",
      "datetime": "2026-08-21T00:00:00Z",
      "domain": "vedic",
      "type": "dasha-change",
      "body": "Saturn-Mercury Antardasha",
      "description": "Vimshottari Mercury Antardasha begins within the Saturn Mahadasha, shifting the active sub-period.",
      "significance": 74
    }
  ]
}
```

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/forecast`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
POST /forecast/timeline                       -> post_forecast_timeline
POST /forecast/transits                       -> post_forecast_transits
POST /forecast/significant-dates              -> post_forecast_significant_dates
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/forecast/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.