Forecast API Reference

Cross-domain 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.

Request

birthData object, required

The single birth subject this forecast is built for. One object only, never an array.

birthData.date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

birthData.time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

birthData.timezone number or string, required

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.

Response

birthData object, required

Echo of the birth subject this forecast was built for.

Show all 5 fieldsShow fewer fields

date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

timezone number, required

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.

latitude number

Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

longitude number

Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

startDate string, required

First day of the resolved forecast window.

endDate string, required

Last day of the resolved forecast window after the horizon clamp.

count number, required

Number of events in the timeline after deduplication, filtering, and the event cap.

events array of object, required

The merged, time-ordered forecast events across the requested domains.

Show all 14 fieldsShow fewer fields

date string, required

Calendar date of the event in YYYY-MM-DD (UTC).

datetime string, required

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.

domain string enum, required

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. One of western, vedic, biorhythm.

type string enum, required

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. One of transit-aspect, sign-ingress, retrograde-station, eclipse, lunar-phase, dasha-change, critical-day.

body string, required

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.

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.

aspect string

For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.

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.

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. One of retrograde, direct.

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. One of penumbral, partial, annular, total.

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.

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. One of new-moon, full-moon.

description string, required

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.

significance number, required

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.

Errors

Western astrology forecast

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.

Request

birthData object, required

The single birth subject this transit forecast is built for. One object only, never an array.

birthData.date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

birthData.time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

birthData.timezone number or string, required

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.

Response

birthData object, required

Echo of the birth subject this forecast was built for.

Show all 5 fieldsShow fewer fields

date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

timezone number, required

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.

latitude number

Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

longitude number

Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

startDate string, required

First day of the resolved forecast window.

endDate string, required

Last day of the resolved forecast window after the horizon clamp.

count number, required

Number of events in the timeline after deduplication, filtering, and the event cap.

events array of object, required

The merged, time-ordered forecast events across the requested domains.

Show all 14 fieldsShow fewer fields

date string, required

Calendar date of the event in YYYY-MM-DD (UTC).

datetime string, required

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.

domain string enum, required

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. One of western, vedic, biorhythm.

type string enum, required

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. One of transit-aspect, sign-ingress, retrograde-station, eclipse, lunar-phase, dasha-change, critical-day.

body string, required

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.

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.

aspect string

For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.

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.

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. One of retrograde, direct.

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. One of penumbral, partial, annular, total.

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.

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. One of new-moon, full-moon.

description string, required

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.

significance number, required

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.

Errors

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.

Request

birthData object, required

The single birth subject this forecast is built for. One object only, never an array.

birthData.date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

birthData.time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

birthData.timezone number or string, required

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.

Response

birthData object, required

Echo of the birth subject this forecast was built for.

Show all 5 fieldsShow fewer fields

date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

timezone number, required

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.

latitude number

Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

longitude number

Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

startDate string, required

First day of the resolved forecast window.

endDate string, required

Last day of the resolved forecast window after the horizon clamp.

count number, required

Number of events in the timeline after deduplication, filtering, and the event cap.

events array of object, required

The merged, time-ordered forecast events across the requested domains.

Show all 14 fieldsShow fewer fields

date string, required

Calendar date of the event in YYYY-MM-DD (UTC).

datetime string, required

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.

domain string enum, required

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. One of western, vedic, biorhythm.

type string enum, required

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. One of transit-aspect, sign-ingress, retrograde-station, eclipse, lunar-phase, dasha-change, critical-day.

body string, required

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.

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.

aspect string

For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.

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.

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. One of retrograde, direct.

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. One of penumbral, partial, annular, total.

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.

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. One of new-moon, full-moon.

description string, required

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.

significance number, required

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.

Errors

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.

Request

birthData object, required

The single birth subject this digest is built for. One object only, never an array.

birthData.date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

birthData.time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

birthData.timezone number or string, required

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.

Response

birthData object, required

Echo of the birth subject this digest was built for.

Show all 5 fieldsShow fewer fields

date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.

time string (time), required

Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.

timezone number, required

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.

latitude number

Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

longitude number

Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.

startDate string, required

Start anchor every window is measured from.

endDate string, required

Last day of the resolved 90 day horizon the timeline was built over before slicing.

windows array of object, required

The four rollups in ascending window length: next 24h, 7d, 30d, and 90d from the start anchor.

Show all 31 fieldsShow fewer fields

days number, required

Length of this window in days forward from the start anchor. One of 1, 7, 30, 90.

from string, required

Inclusive lower bound of the window as an ISO-8601 UTC datetime, the start anchor.

to string, required

Exclusive upper bound of the window as an ISO-8601 UTC datetime, the start anchor plus the window length.

count number, required

Number of events whose datetime falls inside this window.

byDomain object, required

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.

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.

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.

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.

byType object, required

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.

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.

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.

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.

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.

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.

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.

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.

top array of object, required

The highest-significance events in this window, most significant first, up to the requested top count. The same TimelineEvent shape as the timeline endpoints.

top[].date string, required

Calendar date of the event in YYYY-MM-DD (UTC).

top[].datetime string, required

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.

top[].domain string enum, required

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. One of western, vedic, biorhythm.

top[].type string enum, required

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. One of transit-aspect, sign-ingress, retrograde-station, eclipse, lunar-phase, dasha-change, critical-day.

top[].body string, required

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.

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.

top[].aspect string

For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.

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.

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. One of retrograde, direct.

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. One of penumbral, partial, annular, total.

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.

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. One of new-moon, full-moon.

top[].description string, required

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.

top[].significance number, required

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.

Errors

Solar return chart

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.

Request

date string (date), required

Birth date in YYYY-MM-DD format. Anchors the natal Sun longitude the transiting Sun returns to each year.

time string (time), required

Birth time in 24-hour HH:MM:SS format. Pins the exact natal Sun position that defines the solar return moment.

year integer, required

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 number, required

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 number, required

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 number or string, required

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.

Response

birthDate string, required

Echo of the birth date used to find the natal Sun longitude.

solarReturnDate string, required

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 number, required

Year of this solar return. The chart covers the period to the next birthday.

location object, required

Location the return chart was cast for. The Ascendant and house cusps change with this location, the basis of the relocated solar return technique.

Show all 3 fieldsShow fewer fields

latitude number, required

Latitude used for the return chart house cusps and Ascendant.

longitude number, required

Longitude used for local sidereal time and the Midheaven.

timezone number, required

Decimal timezone offset applied to the output datetime.

natalSunPosition object, required

The natal Sun position whose annual return defines this chart.

Show all 3 fieldsShow fewer fields

longitude number, required

Natal Sun ecliptic longitude in degrees from 0 to 360 that the Sun returns to.

sign string, required

Tropical zodiac sign of the natal Sun.

degree number, required

Degree within the sign from 0 to 29.999 that the Sun returns to.

chart object, required

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.

Show all 41 fieldsShow fewer fields

birthDetails object, required

Birth details used to generate this chart.

birthDetails.date string (date), required

Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.

birthDetails.time string (time), required

Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.

birthDetails.latitude number, required

Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.

birthDetails.longitude number, required

Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.

birthDetails.timezone number, required

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.

planets array of object, required

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.

planets[].name string enum, required

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. One of Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith.

planets[].longitude number, required

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.

planets[].latitude number, required

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).

planets[].sign string, required

Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude.

planets[].degree number, required

Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign.

planets[].house integer, required

House placement (1-12). Determined by the selected house system and birth location.

planets[].speed number, required

Daily motion in degrees per day. Negative values indicate retrograde motion.

planets[].isRetrograde boolean, required

Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection.

houses array of object, required

All 12 house cusps calculated using the selected house system.

houses[].number integer, required

House number (1-12). Each house governs specific life themes in Western astrology.

houses[].longitude number, required

Ecliptic longitude of this house cusp in degrees (0-360).

houses[].sign string, required

Zodiac sign on this house cusp. Colors the themes of this life area.

houses[].degree number, required

Degree within the zodiac sign on this cusp (0-29.999).

houseSystem string enum, required

House system used for this chart (placidus, whole-sign, equal, or koch). One of placidus, whole-sign, equal, koch.

aspects array of object, required

All planetary aspects found in this chart with orbs, strength, and applying/separating status.

aspects[].planet1 string enum, required

First planet in the aspect pair. One of Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith.

aspects[].planet2 string enum, required

Second planet in the aspect pair. One of Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith.

aspects[].type string enum, required

Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate. One of CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, SEMI_SEXTILE, QUINCUNX, SEMI_SQUARE, SESQUIQUADRATE.

aspects[].angle number, required

Exact angular separation that defines this aspect type in degrees.

aspects[].orb number, required

Deviation from exact aspect in degrees. Tighter orb means stronger influence.

aspects[].isApplying boolean, required

Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger.

aspects[].strength number, required

Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum.

aspects[].interpretation string enum, required

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. One of harmonious, challenging, neutral.

partOfFortune object, required

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.

partOfFortune.sign string, required

Zodiac sign holding the Part of Fortune.

partOfFortune.degree number, required

Degree within the Part of Fortune sign (0-29.999).

partOfFortune.longitude number, required

Absolute ecliptic longitude of the Part of Fortune (0-360).

partOfFortune.house integer, required

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.

partOfFortune.sect string enum, required

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. One of day, night.

vertex object, required

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.

vertex.sign string, required

Zodiac sign holding the Vertex.

vertex.degree number, required

Degree within the Vertex sign (0-29.999).

vertex.longitude number, required

Absolute ecliptic longitude of the Vertex (0-360).

vertex.house integer, required

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.

Errors