Solar & Lunar Returns API
Find when the apparent Sun or Moon returns to its natal tropical longitude. The result includes all matching crossings within the requested UTC calendar year, with a chart for each event.
POST /v1/astrology/returns50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗
What this API provides.
Find solar or lunar returns in a UTC calendar year, with solved crossing times and return charts at the birth location. Explore real output JSON.
Numerically solved return instants
All crossings within the requested UTC year
Return charts at the original birth coordinates
Send
- A known-time birth object
- body: sun or moon, and the requested year
- Optional house system and interpretation locale
Receive
- Target natal longitude and explicit year policy
- events with exact UTC timestamps and individual chart objects
- location_policy: birth_location
See the calculated chart.
The original renderer uses the exact positions in this example. These are computed charts, not stock diagrams. JSON remains the authoritative source.
Real input. Real output.
Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.
{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"body": "sun",
"year": 2026
}{
"request_id": "9838741c69c8a46add0883b1ca335924",
"api_version": "v1",
"locale": "en",
"data": {
"body": "sun",
"year": 2026,
"target_longitude": 60.19554186,
"events": [
{
"at": "2026-05-21T05:29:16Z",
"chart": {
"birth_time_known": true,
"at": "2026-05-21T05:29:16Z",
"planets": {
"sun": {
"longitude": 60.19554186,
"latitude": 0.0000737,
"distance_au": 1.0120344852,
"sign": "gemini"
},
"moon": {
"longitude": 121.59965619,
"latitude": 2.75306903,
"distance_au": 0.0024656906,
"sign": "leo"
},
"mercury": {
"longitude": 68.20184489,
"latitude": 1.2394133,
"distance_au": 1.277188612,
"sign": "gemini"
},
"venus": {
"longitude": 92.60756404,
"latitude": 1.66637443,
"distance_au": 1.3245237344,
"sign": "cancer"
}
},
"houses": {
"system": "whole_sign",
"ascendant": 69.12270802,
"midheaven": 315.03157848,
"cusps": [
60
]
}
}
}
],
"location_policy": "birth_location",
"year_policy": "UTC_calendar_year_all_crossings"
},
"interpretation": {
"locale": "en",
"kind": "astrology/returns",
"disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
"coverage": {
"total_facts": 29,
"selected_facts": 29,
"omitted_count": 0,
"selection_method": "all-source-facts-v1",
"full_numeric_data_unchanged": true
},
"method": {
"engine": "celestack-original-rules-v1",
"corpus": "celestack-original-compositional-v1",
"corpus_version": "2026-11-17.2",
"fallback_locale": null,
"editorial_status": "agent-authored; independent linguistic review pending",
"predictive_validity": "symbolic interpretations are not scientifically validated predictions",
"chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
},
"items": [
{
"fact_id": "astrology/returns.events.1.chart.planets.sun",
"title": "Return chart · Sun · Gemini",
"text": "Context: Return chart. Sun · Gemini · 0.19554° within the sign. Zodiac: tropical. Symbolic focus: self-expression and direction. Ask a new question and compare more than one perspective. House 1: self-presentation and personal agency. Apply the reflection to a real situation rather than a fixed outcome. Reference time: 2026-05-21T05:29:16Z.",
"source": {
"longitude": 60.19554186,
"latitude": 0.0000737,
"distance_au": 1.0120344852,
"sign": "gemini",
"sign_degree": 0.19554186,
"speed_deg_per_day": 0.96247756,
"retrograde": false,
"house": 1,
"id": "astrology/returns.events.1.chart.planets.sun",
"type": "astro_placement",
"planet": "sun",
"frame": "tropical",
"at": "2026-05-21T05:29:16Z",
"context": [
"return_chart"
]
}
}
]
},
"warnings": [],
"credits_used": 10
}The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.
cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/returns' \
+ --header 'Authorization: Bearer YOUR_API_KEY' \
+ --header 'Content-Type: application/json' \
+ --header 'Idempotency-Key: solar-lunar-returns-api-example-001' \
+ --data '{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"body": "sun",
"year": 2026
}'Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗
Ways to use it.
- Annual solar-return pages
- Monthly lunar-return calendars
- Numerically grounded return-chart exports
12 response locales
English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.
Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.
Limits and interpretation.
- The location is the birth location; relocated return charts are not part of this profile.
- The year is a UTC calendar-year filter, not a promise to return the nearest event around a local birthday.
- A lunar return request normally contains multiple events. Birth time is required.
Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗
Choose your billing.
Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.
Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.
Frequently asked questions.
Does the endpoint return only one lunar return?
No. It returns all matching crossings in the requested UTC calendar year. The full sample JSON preserves the complete events array.
Can I calculate a relocated solar return?
The current profile uses the birth location for each return chart. A separate relocation location is not supported.
What does year mean?
The search starts at January 1 at 00:00 UTC and ends at the following January 1. It selects crossings within that interval rather than the event closest to a local birthday.
What does access cost?
Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 10 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.