3-endpoint solar return family: full chart, AI report, and year signature with 12 monthly slices, lunations, and lunar returns.
<260ms.
The Solar Return API works best alongside other /timing/* endpoints. Add
Three endpoints, one year, fully broken down
From the static chart to the AI report to the time-sliced year
Three endpoints that cover the chart, the interpretation, and the timing of the year
A solar return is the moment the Sun comes back to its exact birth position. That moment opens a 12-month window with its own chart, themes, and timing. Our Solar Return API ships as three endpoints: /charts/solar-return for the static SR chart, /analysis/solar-return-report for the full AI interpretation, and /timing/solar-return for the year signature plus time-slicing. The timing endpoint returns the SR moment in UTC + local time, the structural signature (SR ASC sign and ruler, SR Sun house, key planet placements, key SR aspects), and a time-sliced year: 12 monthly slices mapped to SR house cusps, every lunation inside the year, every lunar return inside the year, and optional outer-planet transits to SR points. Average response time stays under 260ms.
Three endpoints, three jobs.
/charts/solar-return returns the SR chart as a static snapshot: planets, houses, aspects.
Call it when you need to render a wheel.
/analysis/solar-return-report returns the full AI interpretation for the year.
Call it when you need narrative text for a client report.
/timing/solar-return is the new timing-flavored sister.
It returns the SR moment, a structural year signature, and a time-sliced year (months, lunations, lunar returns).
Call it when the question is 'what happens WHEN' during the year.
Most production apps call /timing/solar-return first to drive a calendar view, then call /analysis/solar-return-report on demand for the full text.
Two paths, depending on whether you build the UI or want a finished file.
Path one: POST /api/v3/timing/solar-return returns the structured year analysis as JSON.
Send the subject birth_data plus a return_year and you get back the angular planets, the lord of the year in its SR house, the sect light in house, the SR Ascendant sign, and the SR Moon and Sun by house.
This is the data layer.
Use it when you render your own calendar, dashboard, or chart wheel.
Path two: POST /api/v3/pdf/solar-return-report returns a finished ~34-page document for the same inputs.
Use it when you want a polished report to email or sell with no front-end work.
The PDF is the JSON analysis written up in plain language plus extra sections like Sabian symbols and a hot-months timeline.
Same birth_data and return_year for both, so you can offer the live view and the download from one set of inputs.
POST /api/v3/pdf/solar-return-report (shipped May 2026) returns a premium ~34-page document in any of 11 languages, white-label with your branding.
It opens with the year signature, then walks through almuten figuris, any sect change for the year, the main SR aspects, and repeating signatures that echo across charts.
After that it lays out month-by-month themes, transits to the SR angles, and a hot-months timeline that flags the busiest stretches of the year.
The back half covers each life area and gives a Sabian symbol for key placements.
Inputs are simple: the subject birth_data, a return_year, and an optional return_location for a Hellenistic relocated chart.
If a client spends their birthday in a different city, pass that city as return_location and the whole report recalculates for that place.
/timing/solar-return slices the SR year along three axes.
First, 12 monthly slices: each month of the year is mapped to an SR house cusp, so month 1 belongs to the SR 1st house theme, month 2 to the 2nd, and so on.
This gives a clean monthly storyline.
Second, lunations: every New Moon and Full Moon inside the SR year is returned with date, sign, and house in the SR chart.
Most years contain 12-13 lunations.
Third, lunar returns: every Moon-back-to-its-natal-position event inside the SR year (typically 13-14 per year) with date and key positions.
Add the optional outer-planet transit toggle and you also get Jupiter, Saturn, Uranus, Neptune, and Pluto contacts to SR points.
Same namespace pattern.
/timing/profections/annual returns the activated house and Lord of the Year.
/firdaria returns L1 and L2 periods.
/zodiacal-releasing returns the current period plus Loosing of the Bond and Peak markers.
/timing/solar-return slots into the same /timing/* namespace, so you build one client and switch endpoints without rewriting auth, parsing, or error handling.
The classical workflow: use profections to pick the Lord of the Year, use the solar return year signature to qualify how that Lord shows up, then use the monthly slices and lunations to time specific events inside the year.
All four endpoints share the same shape conventions and same date math.
Think of solar returns as cycles that map to real planning windows.
While teams default to arbitrary Q1 planning, solar returns reveal patterns unique to each person.
The API calculates when leadership will be most innovative, when to push for growth, and when to consolidate.
A CEO with Jupiter in the 10th house of their solar return might see strong visibility and expansion that year.
The new /timing/solar-return endpoint also tells you WHICH month inside that year carries which theme, so 'big launch year' becomes 'big launch in months 5-6 around the Full Moon in the 10th'.
Consulting firms charge $1,000+ for this analysis; your app can return it in 260ms.
Most APIs return a birthday chart and stop.
We return three endpoints that cover chart, report, and timing.
The timing endpoint includes the year signature (SR ASC sign + ruler, SR Sun house, key planets, key aspects), 12 monthly slices, every lunation, every lunar return, and optional outer-planet transits to SR points.
We also support relocated returns for travelers, precession corrections, 23 house systems, and profection integration.
Swiss Ephemeris precision (NASA JPL data).
All in under 260ms with 99.99% calculation accuracy.
Yes.
Enterprise tier supports bulk processing for full leadership teams.
Upload executive birth data, get back synchronized annual forecasts: team dynamics for the year, collaboration windows, individual focus areas, collective opportunities.
Some firms analyze 100+ people to plan org structure and project timing.
Bulk rate: 11,000+ calculations/minute with consistent accuracy.
You can also batch the /timing/solar-return endpoint to build a team calendar view where every executive's 12 monthly slices line up on the same grid.
When someone travels or relocates, their SR chart changes by location.
Our API calculates returns for any global coordinates, showing how different cities change the year signature and the monthly slice structure.
Popular pattern: executives pick where to spend their birthday to shape the year ahead, or companies decide where to base key personnel.
Location can shift the entire annual focus and shift which house each monthly slice activates.
Full global timezone support with historical DST handling.
Everything professional astrologers use: tropical and sidereal zodiacs, 23 house systems, precessed and non-precessed returns, relocated calculations, converse returns, and demi-returns.
Plus business-friendly methods: profection years, annual peak periods, and quarterly breakdowns.
Pick your method or use the recommended defaults.
All methods deliver in <260ms with full docs and examples in multiple languages.
Real numbers.
Consulting firms using our API charge $2,000-10,000 for annual executive forecasts that cost them $0.40 to generate.
Dating apps see 43% higher premium conversions with annual compatibility forecasts.
Wellness platforms report 56% engagement boost with personalized annual themes.
The API pays for itself with 2-3 client reports per month.
Beyond direct revenue, a well-timed product launch or avoided crisis can save millions.
Enterprise at $399/month is less than one hour of consultant fees and gives you unlimited annual intelligence.
Annual strategic planning sessions with 89% improvement in client satisfaction
Founder assessment and timing with 67% better exit timing
Employee development cycles with 45% improvement in retention
Client advisory services with $8K average revenue per report
Personalized annual wellness plans boost engagement by 56%
Optimized project timing and resource planning
| Endpoints | /charts/solar-return, /analysis/solar-return-report, /timing/solar-return |
| /timing/solar-return Response | year_signature, monthly_slices[12], lunations[], lunar_returns[] |
| PDF Report Endpoint | POST /api/v3/pdf/solar-return-report (~34 pages, 11 languages, white-label) |
| PDF + JSON Inputs | birth_data + return_year + optional return_location (Hellenistic relocation) |
| Composite JSON Fields | angular planets, lord of year in SR house, sect light in house, SR Asc sign, SR Moon/Sun by house |
| Year Signature Fields | SR ASC sign + ruler, SR Sun house, key planet positions, key SR aspects |
| Outer-Transit Toggle | Optional Jupiter, Saturn, Uranus, Neptune, Pluto contacts to SR points |
| Namespace Consistency | Same /timing/* pattern as /profections, /firdaria, /zodiacal-releasing |
| API Response Time | <260ms average |
| Calculation Accuracy | 99.99% with Swiss Ephemeris (NASA JPL data) |
| House Systems | 23 systems (Placidus, Whole Sign, Equal, etc.) |
| Bulk Throughput | 11,000+ calculations/minute |
| Date Range | 1800-2400 CE |
| Timezones | All global zones with DST handling |
| Return Types | Solar, Lunar, Planetary, Relocated, Converse |
| Profection Integration | Automatic profection years with Lord of the Year |
| Output Languages | 9 languages with professional interpretations |
| Report Formats | JSON, HTML, PDF with white label available |
| SDK Support | JavaScript, Python, Ruby, PHP, Java |
| Uptime SLA | 99.95% guaranteed with redundant infrastructure |
| Webhook Integration | Birthday and event notifications |
| Feature | Astrology API | Others |
|---|---|---|
| Solar return endpoints | 3 (chart + report + timing) | 1 (chart only) |
| Year signature output | SR ASC + ruler, Sun house, key aspects | Raw chart data only |
| Monthly time-slicing | 12 slices mapped to SR house cusps | Not available |
| Lunations within year | Every New/Full Moon with sign + house | Separate endpoint required |
| Lunar returns within year | All 13-14 returns included | Not available |
| Outer-planet transits to SR points | Optional toggle in same response | Separate transit endpoint |
| Namespace consistency | Same /timing/* shape as profections, firdaria, ZR | Ad-hoc endpoint design |
| Response Time | <260ms | 2-5 seconds |
| House Systems | 23 systems | 4-8 systems |
| Relocated Returns | Any global location | Limited |
| Price | $37/month | $99-299/month |
| Free Tier | 50 calculations/month | No free tier |
Same /timing/* namespace for profections, firdaria, ZR, and solar return
Activated house and Lord of the Year for each SR year
Monthly returns that slot inside the SR year
Period markers and Peaks that frame the SR year
L1 and L2 period rulers that overlap the SR year
Foundation chart referenced by every SR call
Daily timing inside the SR year
Start free, scale as you grow. No hidden fees, no surprises.
For small apps and personal projects
For growing apps and medium traffic
For enterprise-scale applications
All plans include comprehensive documentation and SDKs
Questions? Talk to our team
Real answers about the 3-endpoint family