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, with positions verified against NASA JPL Horizons. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.
5 endpoints. Product page. Typed SDKs in six languages carry every operation below.
POST /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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | number | Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
startDate | string (date) | First day of the forecast window in YYYY-MM-DD format. Defaults to today in UTC. |
endDate | 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 | 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 | number | Drop events scoring below this significance threshold from 0 to 100. Defaults to 0, keeping all events. |
domainWeights | 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 | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.vedic | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.biorhythm | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
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}}'| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | 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. |
| 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 | 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 | string | For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types. |
events[].orb | 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 | 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 | 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 | 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 | 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. |
{
"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
}
]
}POST /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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | number | Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
startDate | string (date) | First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC. |
endDate | 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 | number | Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0. |
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}}'| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | 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. |
| 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 | 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 | string | For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types. |
events[].orb | 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 | 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 | 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 | 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 | 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. |
{
"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
}
]
}POST /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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | number | Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
startDate | string (date) | First day of the window in YYYY-MM-DD format. Defaults to today in UTC. |
endDate | 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 | array of string enum | Which forecast domains to consider before filtering by significance. Defaults to all three. |
minSignificance | number | Significance floor from 0 to 100 for what counts as a significant date. Defaults to 70. |
domainWeights | 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 | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.vedic | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.biorhythm | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
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}}'| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | 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. |
| 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 | 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 | string | For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types. |
events[].orb | 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 | 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 | 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 | 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 | 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. |
{
"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
}
]
}POST /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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | number | Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
startDate | 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 | array of string enum | Which forecast domains to include before rolling up the windows. Defaults to all three. |
minSignificance | number | Drop events scoring below this significance threshold from 0 to 100 before the rollup. Defaults to 0. |
domainWeights | 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 | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.vedic | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
domainWeights.biorhythm | number | Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it. |
top | integer | Number of highest-significance events to surface per window. Defaults to 3, capped at 20. |
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}}'| 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 | number | Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0. |
birthData.longitude | 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. |
| Field | Type | Description |
|---|---|---|
windows[].byDomain.western | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | string | For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types. |
windows[].top[].orb | 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 | 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 | 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 | 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 | 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. |
{
"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
}
]
}
]
}POST /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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| 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 | string enum | House system for the return chart. placidus is the Western default. whole-sign, equal, and koch are also supported. |
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"}'| 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. |
| 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. |
{
"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
}
}
}Hi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.