Astrology Forecast API: Build a Scored Transit Timeline

Building a "what is coming up for this user" feature is one of the hardest things in any spiritual app, and the Forecast API exists to remove that work. Done by hand, it means stitching three engines: transit math that walks planetary positions forward day by day, Vedic dasha timing that tracks mahadasha and antardasha boundaries, and biorhythm cycle tracking, then a scoring layer to decide which of the dozens of resulting events actually matter. The Forecast API collapses all of that into one request. You send a birth date, time, and timezone plus a date range, and you get back a ranked timeline of dated events, each with a significance score so you can show the three that matter instead of a wall of noise. Every position is verified against NASA JPL Horizons, so the math under the timeline is trustworthy.

What does a Forecast API return for a birth chart and date range?

A Forecast API returns a ranked list of dated events for one birth subject across a date range. Each event carries a date, an ISO 8601 datetime, a domain (western, vedic, or biorhythm), a type such as sign-ingress or transit-aspect, a body, a target, an optional aspect and orb, a human-readable description, and a significance score from 0 to 100.

That last field is the citation gold: significance lets you rank and filter events instead of dumping raw astronomy on a user. A typical event from the live API looks like this:

{
  "date": "2026-06-02",
  "domain": "western",
  "type": "transit-aspect",
  "body": "Mercury",
  "target": "Mars",
  "aspect": "sextile",
  "orb": 0,
  "description": "Transiting Mercury sextile natal Mars, an exact aspect within 0 degrees.",
  "significance": 52
}

The body is the transiting planet, target is the natal planet (or the sign for an ingress), and orb is the separation in degrees. A tighter orb means a stronger, higher-scoring event.

Ready to build this? Forecast API gives you a ranked, multi-domain timeline from one call. See pricing.

How does one call blend Western, Vedic, and biorhythm signals?

The domains array controls which signal sets feed the timeline. It accepts western, vedic, and biorhythm and defaults to all three. Western contributes transit aspects, sign ingresses, retrograde stations, and eclipses; Vedic contributes Vimshottari mahadasha and antardasha boundaries as dasha-change events; biorhythm contributes critical days. Every event lands on the same 0 to 100 significance scale, so a transit aspect, a dasha change, and a biorhythm critical day rank directly against each other in one merged timeline.

You shape the result two ways. minSignificance (0 to 100, default 0) drops every event scoring below the threshold before the rollup, which strips low-noise events in one parameter. domainWeights is a per-domain multiplier: pass { "vedic": 1.5, "biorhythm": 0.5 } to promote dasha boundaries and demote biorhythm critical days before filtering, so a Vedic-leaning product and a transit-leaning product can run off the same call with different emphasis. Valid keys are western, vedic, and biorhythm, and omitted domains default to a weight of 1. This single-call breadth is part of one subscription covering 12 insight domains, from Western astrology and Vedic through numerology and tarot, at one flat price.

How do you generate a transit timeline from a birth date?

You generate a timeline in two steps: resolve the birth city to a DST-correct timezone, then post the chart and date range to the Forecast API. The window runs up to 90 days from startDate, and a request with no endDate defaults to 30 days, so a longer forecast is built by paging across consecutive windows. Because the timeline depends only on natal and transiting positions, not on a house layout, birth location is only needed to resolve the timezone, so latitude and longitude stay optional throughout.

First resolve the city. The location search returns a DST-correct IANA timezone you feed straight into birthData.timezone:

curl "https://roxyapi.com/api/v2/location/search?q=Berlin" \
  -H "X-API-Key: $ROXY_KEY"

Each item in the returned cities array carries city, country, latitude, longitude, and timezone (for example "Europe/Berlin"). Pass cities[0].timezone into the request below. The latitude and longitude stay optional for the forecast.

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

const res = await fetch("https://roxyapi.com/api/v2/forecast/transits", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ROXY_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    birthData: {
      date: "1990-07-15",
      time: "13:30:00",
      timezone: "Europe/Berlin",
    },
    startDate: "2026-06-01",
    endDate: "2026-08-01",
    minSignificance: 30,
  }),
});
const { events, count } = await res.json();

import os, requests

res = requests.post(
    "https://roxyapi.com/api/v2/forecast/transits",
    headers={
        "X-API-Key": os.environ["ROXY_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "birthData": {
            "date": "1990-07-15",
            "time": "13:30:00",
            "timezone": "Europe/Berlin",
        },
        "startDate": "2026-06-01",
        "endDate": "2026-08-01",
        "minSignificance": 30,
    },
)
data = res.json()
events = data["events"]

The POST /forecast/transits response returns birthData, startDate, endDate, a count, and the events array. Swap the path to /forecast/timeline and add a domains array to fold Vedic dasha and biorhythm events into the same response. The typed SDKs cover both: @roxyapi/sdk for TypeScript and roxy-sdk for Python, both deriving the forecast namespace from the same spec.

What is the difference between transits, timeline, digest, and significant dates?

The five endpoints share the same birthData and scoring engine but differ in how they shape the output. Transits gives you the raw flat event stream; digest rolls events into grouped time windows; timeline and significant-dates filter and rank across domains; and solar-return computes the chart for a single birthday year. Pick the shape that matches your view, not a different data source.

Digest, timeline, and significant-dates all accept domains, domainWeights, and minSignificance. Digest adds top to cap how many events surface per window. Solar-return takes date, time, latitude, longitude, timezone, a year, and an optional houseSystem of placidus, whole-sign, equal, or koch.

How do you keep a forecast accurate and avoid noise?

Keep a forecast accurate by getting the timezone right and keep it clean by filtering on significance. The natal positions every transit is measured against are anchored by the birth time and timezone, so a wrong offset silently shifts the whole chart and produces a plausible but wrong timeline. Resolve the city through location search to get the DST-correct IANA name rather than hardcoding an offset.

To cut noise, raise minSignificance to drop weak events before they reach your UI, and use top on the digest to cap events per window. Because the same input produces the same output, forecast results for a fixed date range are deterministic and safe to cache in your own store, which flattens both latency and quota cost as your user base grows.

FAQ

Is there an astrology forecast API?

Yes. The RoxyAPI Forecast API is a live, production endpoint set at /api/v2/forecast. It takes a birth date, time, and timezone plus a date range and returns a significance-scored timeline of dated events. It ships five endpoints: transits, digest, timeline, significant-dates, and solar-return.

What does a forecast API return?

It returns a ranked list of dated events for one birth subject. Each event has a date, an ISO datetime, a domain, a type, a body, a target, an optional aspect and orb, a human-readable description, and a significance score from 0 to 100. The score lets you rank and filter, so you show the events that matter instead of every raw astronomical change.

Can one API combine Western and Vedic forecasts?

Yes, and biorhythm too. The domains array accepts western, vedic, and biorhythm and defaults to all three, so a single call blends transit aspects, Vimshottari dasha boundaries, and biorhythm critical days into one ranked timeline. Use domainWeights to promote or demote a domain before the events are filtered and capped.

How is event significance scored?

Every event is scored from 0 to 100 on one scale shared across all three domains, so events rank against each other in a single timeline. Tighter aspects score higher: an exact transit within a 0 degree orb outranks a wide one. Use minSignificance to drop everything below a threshold before the rollup, and top to cap how many events return per window.

How far ahead can a forecast go?

Each call covers up to 90 days from the startDate, and a request with no endDate defaults to a 30 day window. To build a longer forecast, page across consecutive 90 day windows and stitch the results. Each window is deterministic for a fixed birth chart, so every page is safe to cache.

Can I use the Forecast API with AI agents or MCP?

Yes. RoxyAPI ships Remote MCP over Streamable HTTP, so there is no local setup and it runs in seconds with Claude Code, Cursor, and VS Code. An agent can call the forecast tools directly to answer "what is coming up for this birth chart" without you writing glue code. The same flat subscription covers the Remote MCP access and all 12 insight domains.

Conclusion

The Forecast API turns a birth chart and a date range into a ranked, multi-domain timeline from one call, blending Western, Vedic, and biorhythm signals on a single significance scale so you ship a real "what is coming up" feature instead of three engines stitched together. Start with the Forecast API and check the pricing to see every domain included in one subscription.