API Reference

Forecast

Astrology forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm critical days, and Vimshottari dasha changes into one time-ordered forecast for a single subject.

Remote MCP Product page SDKs in 6 languages

Your API keyKept in this tab only. Without a key, a small daily allowance still answers every request on this page.

Cross-domain forecast timeline

POST

https://roxyapi.com/api/v2/forecast/timeline

Build one time-ordered forecast for a single birth subject by merging upcoming events across three domains: western transit-to-natal aspects, sign ingresses, retrograde stations, eclipses, and new and full moons; biorhythm critical days; and vedic Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. The window is clamped to 90 days and events are capped and scored by significance. Built for what-is-coming dashboards, daily and weekly forecast feeds, and timing tools.

Call it

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.forecast.generateTimeline({ body: { birthData: { date: '1990-07-15', time: '13:30:00', timezone: 'America/New_York', latitude: 0, longitude: 0 } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.forecast.generate_timeline(birth_data={'date': '1990-07-15', 'time': '13:30:00', 'timezone': 'America/New_York', 'latitude': 0, 'longitude': 0})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->forecast->generateTimeline(birthData: ['date' => '1990-07-15', 'time' => '13:30:00', 'timezone' => 'America/New_York', 'latitude' => 0, 'longitude' => 0]);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Forecast.Timeline.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Forecast.GenerateTimeline(ctx, nil, roxyapi.GenerateTimelineJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateTimelineParams, body: &types::GenerateTimelineRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.forecast().generate_timeline(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/forecast/timeline" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-07-15","time":"13:30:00","timezone":"America/New_York","latitude":0,"longitude":0}}'

Typed SDKs in 6 languages. On Remote MCP this is the tool post_forecast_timeline on the Forecast server, https://roxyapi.com/mcp/forecast.

Parameters

Request body

Field	Type	Description
`birthData` required	`object`	The single birth subject this forecast is built for. One object only, never an array.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number or string`	IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` optional	`string (date)`	First day of the forecast window in YYYY-MM-DD format. Defaults to today in UTC.
`endDate` optional	`string (date)`	Last day of the forecast window in YYYY-MM-DD format. Defaults to startDate plus 30 days. The window is clamped to a maximum of 90 days from startDate.
`domains` optional	`array of string enum`	Which forecast domains to include. Defaults to all three. Pass a subset to scope the timeline to one or two engines.
`minSignificance` optional	`number`	Drop events scoring below this significance threshold from 0 to 100. Defaults to 0, keeping all events.
`domainWeights` optional	`object`	Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm.
`domainWeights.western` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.vedic` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.biorhythm` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.

Response fields

Field	Type	Description
`birthData` required	`object`	Echo of the birth subject this forecast was built for.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number`	Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth date and time, so this is the literal number applied, never the name.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` required	`string`	First day of the resolved forecast window.
`endDate` required	`string`	Last day of the resolved forecast window after the horizon clamp.
`count` required	`number`	Number of events in the timeline after deduplication, filtering, and the event cap.
`events` required	`array of object`	The merged, time-ordered forecast events across the requested domains.
`events[].date` required	`string`	Calendar date of the event in YYYY-MM-DD (UTC).
`events[].datetime` required	`string`	Exact instant of the event as an ISO-8601 UTC datetime, to the nearest second. Astronomical events are refined to this instant by search, not reported at a daily sample point; a dasha-change is the period boundary itself, counted from the birth instant.
`events[].domain` required	`string enum`	Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
`events[].type` required	`string enum`	Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.

Show all fieldsShow fewer fields

Field	Type	Description
`events[].body` required	`string`	Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, or the critical cycle for biorhythm days. For a dasha-change, the Vimshottari lords outermost first, joined by a hyphen, then one space and the level: Saturn Mahadasha, Saturn-Mercury Antardasha, Saturn-Mercury-Ketu Pratyantardasha. Lords are always one of Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury. Never localized.
`events[].target` optional	`string`	For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
`events[].aspect` optional	`string`	For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.
`events[].orb` optional	`number`	For a transit-aspect, the separation in degrees from the exact aspect at the reported instant, rounded to three decimals. The instant is the moment the aspect perfects, so this reads 0. Absent for other event types.
`events[].station` optional	`string enum`	For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types.
`events[].kind` optional	`string enum`	For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types.
`events[].obscuration` optional	`number`	For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types.
`events[].phase` optional	`string enum`	For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types.
`events[].description` required	`string`	Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English.
`events[].significance` required	`number`	Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on.

Example response

200 OK

{
  "birthData": {
    "date": "1990-07-15",
    "time": "13:30:00",
    "timezone": -4,
    "latitude": 0,
    "longitude": 0
  },
  "startDate": "2026-06-01",
  "endDate": "2026-08-30",
  "count": 42,
  "events": [
    {
      "date": "2026-07-04",
      "datetime": "2026-07-04T08:42:11Z",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Saturn",
      "target": "Moon",
      "aspect": "square",
      "orb": 0,
      "station": "retrograde",
      "kind": "total",
      "obscuration": 0.966,
      "phase": "full-moon",
      "description": "Transiting Saturn square natal Moon, an exact aspect.",
      "significance": 90
    }
  ]
}

Try it

Live

lang

Request bodyJSON, as the example shows it.

Western astrology forecast

POST

https://roxyapi.com/api/v2/forecast/transits

Forecast the western astrology events for a single birth chart over a window up to 90 days: every transit-to-natal major aspect refined to its exact instant, every transiting planet sign ingress, every retrograde or direct station, every solar and lunar eclipse, and every New and Full Moon. Returns a time-ordered, significance-scored timeline. Built for astrology forecast feeds, transit alerts, and timing tools.

Call it

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.forecast.forecastTransits({ body: { birthData: { date: '1990-07-15', time: '13:30:00', timezone: 'America/New_York', latitude: 0, longitude: 0 } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.forecast.forecast_transits(birth_data={'date': '1990-07-15', 'time': '13:30:00', 'timezone': 'America/New_York', 'latitude': 0, 'longitude': 0})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->forecast->forecastTransits(birthData: ['date' => '1990-07-15', 'time' => '13:30:00', 'timezone' => 'America/New_York', 'latitude' => 0, 'longitude' => 0]);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Forecast.Transits.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Forecast.ForecastTransits(ctx, nil, roxyapi.ForecastTransitsJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::ForecastTransitsParams, body: &types::ForecastTransitsRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.forecast().forecast_transits(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/forecast/transits" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-07-15","time":"13:30:00","timezone":"America/New_York","latitude":0,"longitude":0}}'

Typed SDKs in 6 languages. On Remote MCP this is the tool post_forecast_transits on the Forecast server, https://roxyapi.com/mcp/forecast.

Parameters

Parameter	Type	Description
`lang` query, optional	`string enum`	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthData` required	`object`	The single birth subject this transit forecast is built for. One object only, never an array.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number or string`	IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` optional	`string (date)`	First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC.
`endDate` optional	`string (date)`	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` optional	`number`	Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0.

Response fields

Field	Type	Description
`birthData` required	`object`	Echo of the birth subject this forecast was built for.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number`	Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth date and time, so this is the literal number applied, never the name.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` required	`string`	First day of the resolved forecast window.
`endDate` required	`string`	Last day of the resolved forecast window after the horizon clamp.
`count` required	`number`	Number of events in the timeline after deduplication, filtering, and the event cap.
`events` required	`array of object`	The merged, time-ordered forecast events across the requested domains.
`events[].date` required	`string`	Calendar date of the event in YYYY-MM-DD (UTC).
`events[].datetime` required	`string`	Exact instant of the event as an ISO-8601 UTC datetime, to the nearest second. Astronomical events are refined to this instant by search, not reported at a daily sample point; a dasha-change is the period boundary itself, counted from the birth instant.
`events[].domain` required	`string enum`	Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
`events[].type` required	`string enum`	Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.

Show all fieldsShow fewer fields

Field	Type	Description
`events[].body` required	`string`	Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, or the critical cycle for biorhythm days. For a dasha-change, the Vimshottari lords outermost first, joined by a hyphen, then one space and the level: Saturn Mahadasha, Saturn-Mercury Antardasha, Saturn-Mercury-Ketu Pratyantardasha. Lords are always one of Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury. Never localized.
`events[].target` optional	`string`	For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
`events[].aspect` optional	`string`	For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.
`events[].orb` optional	`number`	For a transit-aspect, the separation in degrees from the exact aspect at the reported instant, rounded to three decimals. The instant is the moment the aspect perfects, so this reads 0. Absent for other event types.
`events[].station` optional	`string enum`	For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types.
`events[].kind` optional	`string enum`	For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types.
`events[].obscuration` optional	`number`	For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types.
`events[].phase` optional	`string enum`	For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types.
`events[].description` required	`string`	Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English.
`events[].significance` required	`number`	Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on.

Example response

200 OK

{
  "birthData": {
    "date": "1990-07-15",
    "time": "13:30:00",
    "timezone": -4,
    "latitude": 0,
    "longitude": 0
  },
  "startDate": "2026-06-01",
  "endDate": "2026-08-30",
  "count": 42,
  "events": [
    {
      "date": "2026-07-04",
      "datetime": "2026-07-04T08:42:11Z",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Saturn",
      "target": "Moon",
      "aspect": "square",
      "orb": 0,
      "station": "retrograde",
      "kind": "total",
      "obscuration": 0.966,
      "phase": "full-moon",
      "description": "Transiting Saturn square natal Moon, an exact aspect.",
      "significance": 90
    }
  ]
}

Try it

Live

lang

Request bodyJSON, as the example shows it.

Significant dates

POST

https://roxyapi.com/api/v2/forecast/significant-dates

Return only the high-significance dates from the merged cross-domain forecast for a single birth subject: the rare outer-planet exact transit aspects, slow-planet sign ingresses, retrograde stations, and Vimshottari mahadasha and antardasha changes that mark genuine turning points. Defaults to a significance floor of 70 so the response is a short list of the most meaningful upcoming dates. Built for what-is-coming highlights, timing alerts, and at-a-glance forecast strips.

Call it

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.forecast.findSignificantDates({ body: { birthData: { date: '1990-07-15', time: '13:30:00', timezone: 'America/New_York', latitude: 0, longitude: 0 } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.forecast.find_significant_dates(birth_data={'date': '1990-07-15', 'time': '13:30:00', 'timezone': 'America/New_York', 'latitude': 0, 'longitude': 0})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->forecast->findSignificantDates(birthData: ['date' => '1990-07-15', 'time' => '13:30:00', 'timezone' => 'America/New_York', 'latitude' => 0, 'longitude' => 0]);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Forecast.SignificantDates.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Forecast.FindSignificantDates(ctx, nil, roxyapi.FindSignificantDatesJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::FindSignificantDatesParams, body: &types::FindSignificantDatesRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.forecast().find_significant_dates(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/forecast/significant-dates" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-07-15","time":"13:30:00","timezone":"America/New_York","latitude":0,"longitude":0}}'

Typed SDKs in 6 languages. On Remote MCP this is the tool post_forecast_significant_dates on the Forecast server, https://roxyapi.com/mcp/forecast.

Parameters

Parameter	Type	Description
`lang` query, optional	`string enum`	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthData` required	`object`	The single birth subject this forecast is built for. One object only, never an array.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number or string`	IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` optional	`string (date)`	First day of the window in YYYY-MM-DD format. Defaults to today in UTC.
`endDate` optional	`string (date)`	Last day of the window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate.
`domains` optional	`array of string enum`	Which forecast domains to consider before filtering by significance. Defaults to all three.
`minSignificance` optional	`number`	Significance floor from 0 to 100 for what counts as a significant date. Defaults to 70.
`domainWeights` optional	`object`	Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm.
`domainWeights.western` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.vedic` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.biorhythm` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.

Response fields

Field	Type	Description
`birthData` required	`object`	Echo of the birth subject this forecast was built for.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number`	Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth date and time, so this is the literal number applied, never the name.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` required	`string`	First day of the resolved forecast window.
`endDate` required	`string`	Last day of the resolved forecast window after the horizon clamp.
`count` required	`number`	Number of events in the timeline after deduplication, filtering, and the event cap.
`events` required	`array of object`	The merged, time-ordered forecast events across the requested domains.
`events[].date` required	`string`	Calendar date of the event in YYYY-MM-DD (UTC).
`events[].datetime` required	`string`	Exact instant of the event as an ISO-8601 UTC datetime, to the nearest second. Astronomical events are refined to this instant by search, not reported at a daily sample point; a dasha-change is the period boundary itself, counted from the birth instant.
`events[].domain` required	`string enum`	Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
`events[].type` required	`string enum`	Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.

Show all fieldsShow fewer fields

Field	Type	Description
`events[].body` required	`string`	Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, or the critical cycle for biorhythm days. For a dasha-change, the Vimshottari lords outermost first, joined by a hyphen, then one space and the level: Saturn Mahadasha, Saturn-Mercury Antardasha, Saturn-Mercury-Ketu Pratyantardasha. Lords are always one of Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury. Never localized.
`events[].target` optional	`string`	For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
`events[].aspect` optional	`string`	For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.
`events[].orb` optional	`number`	For a transit-aspect, the separation in degrees from the exact aspect at the reported instant, rounded to three decimals. The instant is the moment the aspect perfects, so this reads 0. Absent for other event types.
`events[].station` optional	`string enum`	For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types.
`events[].kind` optional	`string enum`	For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types.
`events[].obscuration` optional	`number`	For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types.
`events[].phase` optional	`string enum`	For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types.
`events[].description` required	`string`	Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English.
`events[].significance` required	`number`	Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on.

Example response

200 OK

{
  "birthData": {
    "date": "1990-07-15",
    "time": "13:30:00",
    "timezone": -4,
    "latitude": 0,
    "longitude": 0
  },
  "startDate": "2026-06-01",
  "endDate": "2026-08-30",
  "count": 42,
  "events": [
    {
      "date": "2026-07-04",
      "datetime": "2026-07-04T08:42:11Z",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Saturn",
      "target": "Moon",
      "aspect": "square",
      "orb": 0,
      "station": "retrograde",
      "kind": "total",
      "obscuration": 0.966,
      "phase": "full-moon",
      "description": "Transiting Saturn square natal Moon, an exact aspect.",
      "significance": 90
    }
  ]
}

Try it

Live

lang

Request bodyJSON, as the example shows it.

Forecast digest

POST

https://roxyapi.com/api/v2/forecast/digest

Roll the cross-domain forecast for a single birth subject into four pre-summarized windows: the next 24 hours, 7 days, 30 days, and 90 days from the start date. Each window returns its event count, a per-domain count breakdown, a per-type count breakdown, and the top highest-significance events. Built for a glanceable what-is-coming strip so a caller can render the upcoming highlights without scanning the full event list.

Call it

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.forecast.generateDigest({ body: { birthData: { date: '1990-07-15', time: '13:30:00', timezone: 'America/New_York', latitude: 0, longitude: 0 } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.forecast.generate_digest(birth_data={'date': '1990-07-15', 'time': '13:30:00', 'timezone': 'America/New_York', 'latitude': 0, 'longitude': 0})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->forecast->generateDigest(birthData: ['date' => '1990-07-15', 'time' => '13:30:00', 'timezone' => 'America/New_York', 'latitude' => 0, 'longitude' => 0]);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Forecast.Digest.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Forecast.GenerateDigest(ctx, nil, roxyapi.GenerateDigestJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateDigestParams, body: &types::GenerateDigestRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.forecast().generate_digest(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/forecast/digest" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-07-15","time":"13:30:00","timezone":"America/New_York","latitude":0,"longitude":0}}'

Typed SDKs in 6 languages. On Remote MCP this is the tool post_forecast_digest on the Forecast server, https://roxyapi.com/mcp/forecast.

Parameters

Parameter	Type	Description
`lang` query, optional	`string enum`	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthData` required	`object`	The single birth subject this digest is built for. One object only, never an array.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number or string`	IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` optional	`string (date)`	Start anchor for every window in YYYY-MM-DD format. The next 24h, 7d, 30d, and 90d windows are measured forward from this date at 00:00:00 UTC. Defaults to today in UTC.
`domains` optional	`array of string enum`	Which forecast domains to include before rolling up the windows. Defaults to all three.
`minSignificance` optional	`number`	Drop events scoring below this significance threshold from 0 to 100 before the rollup. Defaults to 0.
`domainWeights` optional	`object`	Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm.
`domainWeights.western` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.vedic` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`domainWeights.biorhythm` optional	`number`	Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
`top` optional	`integer`	Number of highest-significance events to surface per window. Defaults to 3, capped at 20.

Response fields

Field	Type	Description
`birthData` required	`object`	Echo of the birth subject this digest was built for.
`birthData.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
`birthData.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
`birthData.timezone` required	`number`	Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth date and time, so this is the literal number applied, never the name.
`birthData.latitude` optional	`number`	Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`birthData.longitude` optional	`number`	Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
`startDate` required	`string`	Start anchor every window is measured from.
`endDate` required	`string`	Last day of the resolved 90 day horizon the timeline was built over before slicing.
`windows` required	`array of object`	The four rollups in ascending window length: next 24h, 7d, 30d, and 90d from the start anchor.
`windows[].days` required	`number`	Length of this window in days forward from the start anchor. One of 1, 7, 30, 90.
`windows[].from` required	`string`	Inclusive lower bound of the window as an ISO-8601 UTC datetime, the start anchor.
`windows[].to` required	`string`	Exclusive upper bound of the window as an ISO-8601 UTC datetime, the start anchor plus the window length.
`windows[].count` required	`number`	Number of events whose datetime falls inside this window.
`windows[].byDomain` required	`object`	Count of events in this window broken down by domain. Only domains with at least one event in the window are present. The values sum to count.

Show all fieldsShow fewer fields

Field	Type	Description
`windows[].byDomain.western` optional	`number`	Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written.
`windows[].byDomain.vedic` optional	`number`	Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written.
`windows[].byDomain.biorhythm` optional	`number`	Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written.
`windows[].byType` required	`object`	Count of events in this window broken down by event type. Only types with at least one event in the window are present. The values sum to count.
`windows[].byType.transit-aspect` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.sign-ingress` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.retrograde-station` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.eclipse` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.lunar-phase` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.dasha-change` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].byType.critical-day` optional	`number`	Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written.
`windows[].top` required	`array of object`	The highest-significance events in this window, most significant first, up to the requested top count. The same TimelineEvent shape as the timeline endpoints.
`windows[].top[].date` required	`string`	Calendar date of the event in YYYY-MM-DD (UTC).
`windows[].top[].datetime` required	`string`	Exact instant of the event as an ISO-8601 UTC datetime, to the nearest second. Astronomical events are refined to this instant by search, not reported at a daily sample point; a dasha-change is the period boundary itself, counted from the birth instant.
`windows[].top[].domain` required	`string enum`	Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
`windows[].top[].type` required	`string enum`	Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.
`windows[].top[].body` required	`string`	Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, or the critical cycle for biorhythm days. For a dasha-change, the Vimshottari lords outermost first, joined by a hyphen, then one space and the level: Saturn Mahadasha, Saturn-Mercury Antardasha, Saturn-Mercury-Ketu Pratyantardasha. Lords are always one of Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury. Never localized.
`windows[].top[].target` optional	`string`	For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
`windows[].top[].aspect` optional	`string`	For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.
`windows[].top[].orb` optional	`number`	For a transit-aspect, the separation in degrees from the exact aspect at the reported instant, rounded to three decimals. The instant is the moment the aspect perfects, so this reads 0. Absent for other event types.
`windows[].top[].station` optional	`string enum`	For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types.
`windows[].top[].kind` optional	`string enum`	For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types.
`windows[].top[].obscuration` optional	`number`	For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types.
`windows[].top[].phase` optional	`string enum`	For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types.
`windows[].top[].description` required	`string`	Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English.
`windows[].top[].significance` required	`number`	Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on.

Example response

200 OK

{
  "birthData": {
    "date": "1990-07-15",
    "time": "13:30:00",
    "timezone": -4,
    "latitude": 0,
    "longitude": 0
  },
  "startDate": "2026-06-01",
  "endDate": "2026-08-29",
  "windows": [
    {
      "days": 7,
      "from": "2026-06-01T00:00:00Z",
      "to": "2026-06-08T00:00:00Z",
      "count": 5,
      "byDomain": {
        "western": 3,
        "vedic": 1,
        "biorhythm": 1
      },
      "byType": {
        "transit-aspect": 3,
        "sign-ingress": 1,
        "critical-day": 1
      },
      "top": [
        {
          "date": "2026-07-04",
          "datetime": "2026-07-04T08:42:11Z",
          "domain": "western",
          "type": "transit-aspect",
          "body": "Saturn",
          "target": "Moon",
          "aspect": "square",
          "orb": 0,
          "station": "retrograde",
          "kind": "total",
          "obscuration": 0.966,
          "phase": "full-moon",
          "description": "Transiting Saturn square natal Moon, an exact aspect.",
          "significance": 90
        }
      ]
    }
  ]
}

Try it

Live

lang

Request bodyJSON, as the example shows it.

Solar return chart

POST

https://roxyapi.com/api/v2/forecast/solar-return

Cast the solar return chart for one subject and year: the chart erected for the exact moment the transiting Sun returns to its natal ecliptic longitude, the foundational technique for annual astrological forecasting. Returns the full tropical chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Location-sensitive: pass the birthplace to anchor the chart to natal geography, or the current city for a relocated solar return where the houses and Ascendant shift to where you are on your birthday. Built for year-ahead forecast tools, birthday charts, and annual horoscope features.

Call it

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.forecast.forecastSolarReturn({ body: { date: '1990-07-15', time: '14:30:00', year: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.forecast.forecast_solar_return(date='1990-07-15', time='14:30:00', year=2026, latitude=40.7128, longitude=-74.006, timezone='America/New_York')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->forecast->forecastSolarReturn(date: '1990-07-15', time: '14:30:00', year: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Forecast.SolarReturn.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Forecast.ForecastSolarReturn(ctx, nil, roxyapi.ForecastSolarReturnJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::ForecastSolarReturnParams, body: &types::ForecastSolarReturnRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.forecast().forecast_solar_return(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/forecast/solar-return" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-15","time":"14:30:00","year":2026,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'

Typed SDKs in 6 languages. On Remote MCP this is the tool post_forecast_solar_return on the Forecast server, https://roxyapi.com/mcp/forecast.

Parameters

Parameter	Type	Description
`lang` query, optional	`string enum`	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`date` required	`string (date)`	Birth date in YYYY-MM-DD format. Anchors the natal Sun longitude the transiting Sun returns to each year.
`time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Pins the exact natal Sun position that defines the solar return moment.
`year` required	`integer`	Year to cast the solar return for. The chart is erected for the moment in this year when the transiting Sun returns to the natal Sun longitude, on or within a day of the birthday.
`latitude` required	`number`	Latitude of the solar return location in decimal degrees. The solar return is location-sensitive: use the birthplace to anchor the chart to natal geography, or the current city for a relocated solar return.
`longitude` required	`number`	Longitude of the solar return location in decimal degrees. Sets the local sidereal time, so it drives the Ascendant, Midheaven, and house cusps of the return chart.
`timezone` required	`number or string`	IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`houseSystem` optional	`string enum`	House system for the return chart. placidus is the Western default. whole-sign, equal, and koch are also supported.

Response fields

Field	Type	Description
`birthDate` required	`string`	Echo of the birth date used to find the natal Sun longitude.
`solarReturnDate` required	`string`	Exact solar return moment, when the transiting Sun returns to the natal Sun longitude, formatted in the requested timezone. The astrological birthday for the year.
`solarReturnYear` required	`number`	Year of this solar return. The chart covers the period to the next birthday.
`location` required	`object`	Location the return chart was cast for. The Ascendant and house cusps change with this location, the basis of the relocated solar return technique.
`location.latitude` required	`number`	Latitude used for the return chart house cusps and Ascendant.
`location.longitude` required	`number`	Longitude used for local sidereal time and the Midheaven.
`location.timezone` required	`number`	Decimal timezone offset applied to the output datetime.
`natalSunPosition` required	`object`	The natal Sun position whose annual return defines this chart.
`natalSunPosition.longitude` required	`number`	Natal Sun ecliptic longitude in degrees from 0 to 360 that the Sun returns to.
`natalSunPosition.sign` required	`string`	Tropical zodiac sign of the natal Sun.
`natalSunPosition.degree` required	`number`	Degree within the sign from 0 to 29.999 that the Sun returns to.
`chart` required	`object`	Full chart erected for the solar return moment: all bodies with house placements, the 12 house cusps, aspects, Part of Fortune, and Vertex in the tropical zodiac.
`chart.birthDetails` required	`object`	Birth details used to generate this chart.
`chart.birthDetails.date` required	`string (date)`	Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.

Show all fieldsShow fewer fields

Field	Type	Description
`chart.birthDetails.time` required	`string (time)`	Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.
`chart.birthDetails.latitude` required	`number`	Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
`chart.birthDetails.longitude` required	`number`	Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
`chart.birthDetails.timezone` required	`number`	Timezone offset from UTC in decimal hours, resolved for the birth date. Examples: New York = -5 in winter and -4 in summer, London = 0, India = 5.5, Tokyo = 9.
`chart.planets` required	`array of object`	All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith. Chiron is included for charts from 1600 to 2500 and omitted outside that range.
`chart.planets[].name` required	`string enum`	Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The lunar nodes follow the request nodeType, which defaults to the true (osculating) node; pass "mean" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected.
`chart.planets[].longitude` required	`number`	Apparent geocentric tropical longitude on the true ecliptic of date, in degrees (0-360): light time and aberration applied, nutation included, the convention desktop chart software and the NASA JPL Horizons observer tables print, so it compares directly with either. Primary coordinate for zodiac sign and aspect calculations.
`chart.planets[].latitude` required	`number`	Apparent geocentric ecliptic latitude of date, in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit).
`chart.planets[].sign` required	`string`	Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude.
`chart.planets[].degree` required	`number`	Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign.
`chart.planets[].house` required	`integer`	House placement (1-12). Determined by the selected house system and birth location.
`chart.planets[].speed` required	`number`	Daily motion in degrees per day. Negative values indicate retrograde motion.
`chart.planets[].isRetrograde` required	`boolean`	Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection.
`chart.houses` required	`array of object`	All 12 house cusps calculated using the selected house system.
`chart.houses[].number` required	`integer`	House number (1-12). Each house governs specific life themes in Western astrology.
`chart.houses[].longitude` required	`number`	Ecliptic longitude of this house cusp in degrees (0-360).
`chart.houses[].sign` required	`string`	Zodiac sign on this house cusp. Colors the themes of this life area.
`chart.houses[].degree` required	`number`	Degree within the zodiac sign on this cusp (0-29.999).
`chart.houseSystem` required	`string enum`	House system used for this chart (placidus, whole-sign, equal, or koch).
`chart.aspects` required	`array of object`	All planetary aspects found in this chart with orbs, strength, and applying/separating status.
`chart.aspects[].planet1` required	`string enum`	First planet in the aspect pair.
`chart.aspects[].planet2` required	`string enum`	Second planet in the aspect pair.
`chart.aspects[].type` required	`string enum`	Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate.
`chart.aspects[].angle` required	`number`	Exact angular separation that defines this aspect type in degrees.
`chart.aspects[].orb` required	`number`	Deviation from exact aspect in degrees. Tighter orb means stronger influence.
`chart.aspects[].isApplying` required	`boolean`	Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger.
`chart.aspects[].strength` required	`number`	Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum.
`chart.aspects[].interpretation` required	`string enum`	Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees.
`chart.partOfFortune` required	`object`	Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart.
`chart.partOfFortune.sign` required	`string`	Zodiac sign holding the Part of Fortune.
`chart.partOfFortune.degree` required	`number`	Degree within the Part of Fortune sign (0-29.999).
`chart.partOfFortune.longitude` required	`number`	Absolute ecliptic longitude of the Part of Fortune (0-360).
`chart.partOfFortune.house` required	`integer`	House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign.
`chart.partOfFortune.sect` required	`string enum`	Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon.
`chart.vertex` required	`object`	Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex.
`chart.vertex.sign` required	`string`	Zodiac sign holding the Vertex.
`chart.vertex.degree` required	`number`	Degree within the Vertex sign (0-29.999).
`chart.vertex.longitude` required	`number`	Absolute ecliptic longitude of the Vertex (0-360).
`chart.vertex.house` required	`integer`	House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign.

Example response

200 OK

{
  "birthDate": "1990-07-15",
  "solarReturnDate": "2026-07-15T08:42:11",
  "solarReturnYear": 2026,
  "location": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": -4
  },
  "natalSunPosition": {
    "longitude": 112.45,
    "sign": "Cancer",
    "degree": 22.45
  },
  "chart": {
    "birthDetails": {
      "date": "1990-07-15",
      "time": "14:30:00",
      "latitude": 40.7128,
      "longitude": -74.006,
      "timezone": -4
    },
    "planets": [
      {
        "name": "Sun",
        "longitude": 112.45,
        "latitude": 0.01,
        "sign": "Cancer",
        "degree": 22.45,
        "house": 7,
        "speed": 0.9571,
        "isRetrograde": false
      }
    ],
    "houses": [
      {
        "number": 1,
        "longitude": 45.32,
        "sign": "Taurus",
        "degree": 15.32
      }
    ],
    "houseSystem": "placidus",
    "aspects": [
      {
        "planet1": "Sun",
        "planet2": "Moon",
        "type": "TRINE",
        "angle": 120,
        "orb": 2.5,
        "isApplying": true,
        "strength": 75,
        "interpretation": "harmonious"
      }
    ],
    "partOfFortune": {
      "sign": "Aries",
      "degree": 27.24,
      "longitude": 27.24,
      "house": 8,
      "sect": "night"
    },
    "vertex": {
      "sign": "Virgo",
      "degree": 12.9,
      "longitude": 162.9,
      "house": 6
    }
  }
}

Try it

Live

lang

Request bodyJSON, as the example shows it.

Sunbelt Computer Software

PL/B Language Development and Support

Forecast

Cross-domain forecast timeline

Western astrology forecast

Significant dates

Forecast digest

Solar return chart