transit-forecast-api

Transit Forecast API

Transit forecast API for astrology transits over a window up to 90 days. Every transit to natal aspect, sign ingress, retrograde and direct station, eclipse, and new and full moon, each refined to its exact instant and significance scored. One key covers 18+ spiritual domains. MCP-first, verified against NASA JPL Horizons.

What is Transit Forecast API

A transit forecast maps the astrology transits ahead: as the sky moves, transiting planets form aspects to the positions in a birth chart, cross into new signs, and turn retrograde or direct. This repo ships working TypeScript, JavaScript, and Python samples against the RoxyAPI forecast endpoint. Pass one birth chart and a window up to 90 days and the transit forecast returns a time ordered, significance scored timeline: every transit to natal major aspect refined to its exact instant, every sign ingress, every retrograde or direct station, every solar and lunar eclipse, and every new and full moon. One subscription unlocks 18+ spiritual domains: Western astrology, Vedic astrology, Forecast, Human Design, Chinese astrology, Feng Shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, and location. Every position is computed by Roxy Ephemeris, verified against NASA JPL Horizons.

Why this API

Property	Value
Coverage	18+ spiritual domains in one subscription
Calculation	Roxy Ephemeris, verified against NASA JPL Horizons
MCP server	https://roxyapi.com/mcp/forecast (Streamable HTTP, no local setup)
SDKs	TypeScript on npm @roxyapi/sdk, Python on PyPI roxy-sdk, PHP on Packagist roxyapi/sdk, C# on NuGet RoxyApi.Sdk, Go github.com/RoxyAPI/sdk-go, WordPress plugin roxyapi
Pricing	One key, flat per call, from $39/mo
Licensing	Personal and commercial use, including closed source apps. No AGPL or GPL entanglement. Full terms
Last verified	2026-Q3

Quick start

1. Get a key at roxyapi.com/pricing
2. Pick a language below
3. Copy the snippet, run, ship

The forecast is driven by the birth instant and timezone, not the observer location, so latitude and longitude are optional. Pass the birth date, time, and timezone and you have a transit forecast.

cURL

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

Python

import os
from roxy_sdk import create_roxy

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

# Forecast the astrology transits for one birth chart over the next 90 days
result = roxy.forecast.forecast_transits(
    birth_data={
        "date": "1990-07-15",
        "time": "13:30:00",
        "timezone": "America/New_York",
    },
    start_date="2026-07-08",
    end_date="2026-10-05",
    min_significance=50,
)

print("Window:", result["startDate"], "to", result["endDate"], "events:", result["count"])
for e in result["events"][:5]:
    print(e["date"], e["type"], e["body"], "significance", e["significance"])
    print("  ", e["description"])

JavaScript (Node)

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY);

// Forecast the astrology transits for one birth chart over the next 90 days
const { data, error } = await roxy.forecast.forecastTransits({
  body: {
    birthData: {
      date: '1990-07-15',
      time: '13:30:00',
      timezone: 'America/New_York',
    },
    startDate: '2026-07-08',
    endDate: '2026-10-05',
    minSignificance: 50,
  },
});

if (error) throw new Error(error.error);

console.log('Window:', data.startDate, 'to', data.endDate, 'events:', data.count);
data.events.slice(0, 5).forEach(e =>
  console.log(e.date, e.type, e.body, 'significance', e.significance)
);

TypeScript

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

// Forecast the astrology transits for one birth chart over a window up to 90 days
const { data, error } = await roxy.forecast.forecastTransits({
  body: {
    birthData: {
      date: '1990-07-15',
      time: '13:30:00',
      timezone: 'America/New_York',
    },
    startDate: '2026-07-08',
    endDate: '2026-10-05',
    minSignificance: 50,
  },
});

if (error) throw new Error(error.error);

console.log(`Window: ${data.startDate} to ${data.endDate}, ${data.count} events`);
for (const e of data.events.slice(0, 5)) {
  const detail = e.aspect ? `${e.aspect} natal ${e.target}` : e.target ?? '';
  console.log(`${e.date}  ${e.type}  ${e.body} ${detail}  significance ${e.significance}`);
  console.log('  ', e.description);
}

Request schema

Field	Type	Required	Description
birthData	object	yes	The single birth subject this transit forecast is built for. One object only, never an array
birthData.date	string	yes	Birth date in YYYY-MM-DD format. Anchors the natal chart the transit aspects are measured against
birthData.time	string	yes	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against
birthData.timezone	number or string	yes	Decimal hours from UTC (e.g. -5, 5.5) OR an IANA name (e.g. "America/New_York", "Asia/Kolkata"). IANA strings resolve to the DST-correct offset for the birth date
birthData.latitude	number	no	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0
birthData.longitude	number	no	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0
startDate	string	no	First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC
endDate	string	no	Last day of the transit window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate
minSignificance	number	no	Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0

Response shape

{
  "birthData": {
    "date": "1990-07-15",
    "time": "13:30:00",
    "timezone": -4,
    "latitude": 0,
    "longitude": 0
  },
  "startDate": "2026-07-08",
  "endDate": "2026-10-05",
  "count": 117,
  "events": [
    {
      "date": "2026-07-08",
      "datetime": "2026-07-08T05:23:56Z",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Venus",
      "target": "Black Moon Lilith",
      "aspect": "square",
      "orb": 0,
      "description": "Transiting Venus square natal Black Moon Lilith, an exact aspect within 0 degrees.",
      "significance": 52
    },
    {
      "date": "2026-07-09",
      "datetime": "2026-07-09T17:17:05Z",
      "domain": "western",
      "type": "sign-ingress",
      "body": "Venus",
      "target": "Virgo",
      "description": "Venus enters Virgo, beginning a new sign cycle.",
      "significance": 30
    },
    {
      "date": "2026-07-14",
      "datetime": "2026-07-14T09:44:04Z",
      "domain": "western",
      "type": "lunar-phase",
      "body": "Moon",
      "target": "Cancer",
      "phase": "new-moon",
      "description": "New Moon in Cancer, a fresh lunar cycle and a natural reset point for new intentions.",
      "significance": 50
    },
    {
      "date": "2026-07-23",
      "datetime": "2026-07-23T10:55:13Z",
      "domain": "western",
      "type": "retrograde-station",
      "body": "Mercury",
      "station": "direct",
      "description": "Mercury stations direct, releasing forward motion in its themes.",
      "significance": 52
    },
    {
      "date": "2026-08-12",
      "datetime": "2026-08-12T17:45:46Z",
      "domain": "western",
      "type": "eclipse",
      "body": "Sun",
      "kind": "total",
      "description": "total solar eclipse as the New Moon aligns with the Sun, a major timing event that opens a new chapter.",
      "significance": 95
    }
  ]
}

Field	Type	Description
birthData	object	Echo of the birth subject this forecast was built for, with the timezone resolved to a decimal offset
startDate	string	First day of the resolved forecast window
endDate	string	Last day of the resolved forecast window after the 90 day horizon clamp
count	number	Number of events in the timeline after deduplication, filtering, and the event cap
events	array	The time ordered forecast events, sorted strictly ascending by datetime
events[].datetime	string	Exact instant of the event as an ISO-8601 UTC datetime, refined by search rather than reported at a daily sample point
events[].domain	string	Forecast domain. Always western for this endpoint. A stable machine value, never localized
events[].type	string	Event kind: transit-aspect, sign-ingress, retrograde-station, eclipse, or lunar-phase. A stable machine value, never localized
events[].body	string	Primary subject of the event: the transiting planet, Sun for a solar eclipse, or Moon for a lunar eclipse or a new or full moon
events[].target	string	For a transit-aspect, the natal body aspected. For a sign-ingress, the sign entered. For a lunar-phase, the sign of the New or Full Moon. Absent for other event types
events[].aspect	string	For a transit-aspect, the angular relationship: conjunction, sextile, square, trine, or opposition. Absent for other event types
events[].orb	number	For a transit-aspect, the separation in degrees from the exact aspect. Tighter orb means a more exact and significant aspect
events[].station	string	For a retrograde-station, whether the planet turns retrograde or direct. Absent for other event types
events[].kind	string	For an eclipse, its classification: penumbral, partial, annular, or total. Absent for other event types
events[].phase	string	For a lunar-phase, new-moon or full-moon. Absent for other event types
events[].description	string	Plain-language summary of the event, ready to display. The only localized field: with ?lang= set, this sentence renders in the requested language while the structured fields stay English
events[].significance	number	Importance score from 0 to 100. Outer-planet exact aspects and eclipses score highest, fast Moon events lower

Common use cases

Use case	Endpoint flow
Astrology forecast feed	POST to /forecast/transits, render events[] as a scrollable what-is-coming feed sorted by datetime
Transit alerts and push notifications	Filter events[] by minSignificance, fire an alert per event at its datetime
Timing tool for the days ahead	Read aspect, target, and orb from each transit-aspect to surface exact-aspect days
Retrograde and station calendar	Filter events[] to type of retrograde-station, group by body and station
New and full moon and eclipse strip	Filter events[] to type of lunar-phase and eclipse, plot datetime and target sign
Cross-domain what-is-coming digest	Switch to /forecast/timeline to merge these transits with Vimshottari dasha changes and biorhythm critical days

Related endpoints in this domain

• POST /forecast/timeline (generateTimeline) - one merged, time ordered forecast across Western transits, Vedic Vimshottari dasha changes, and biorhythm critical days
• POST /forecast/significant-dates (findSignificantDates) - only the high-significance turning points from the merged cross-domain forecast, defaulting to a significance floor of 70
• POST /forecast/solar-return (forecastSolarReturn) - the full solar return chart for a birthday year, anchored to the birthplace or a relocated city

Use this in your AI agent

Connect Claude, GPT, Gemini, or Cursor to RoxyAPI through the remote MCP server. No Docker. No self hosting. The full MCP tool catalog for this domain is at https://roxyapi.com/mcp/forecast.

{
  "mcpServers": {
    "forecast": {
      "url": "https://roxyapi.com/mcp/forecast",
      "headers": { "X-API-Key": "$ROXY_API_KEY" }
    }
  }
}

See docs/mcp for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code setup.

For AI coding agents

This repo ships an AGENTS.md execution playbook. Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, and Gemini CLI will pick it up automatically. Top level overview lives at roxyapi.com/AGENTS.md.

Resources

• Methodology and gold standard tests verified against NASA JPL Horizons
• Full API reference interactive Scalar UI
• TypeScript SDK on npm
• Python SDK on PyPI
• PHP SDK on Packagist
• C# SDK on NuGet
• Go SDK on pkg.go.dev
• WordPress plugin
• llms.txt full LLM citation index
• Top level AGENTS.md

Other RoxyAPI samples

License

MIT for this sample repo. See LICENSE.

Catalog licensing: Personal and commercial use, including closed source proprietary apps. No AGPL or GPL entanglement. RoxyAPI APIs and SDKs are safe to embed in commercial products. Full terms at roxyapi.com/policy/license.

Contact

• Site: roxyapi.com
• Status: roxyapi.com/api-reference