WESTERN ASTROLOGY · JSON REST API

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.

AvailablePOST /v1/astrology/returns

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

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.

01

Choose the Sun or Moon as the returning body

02

Numerically solved return instants

03

All crossings within the requested UTC year

04

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
FROM THE NUMERICAL RESULT

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.

First return chart in the requested UTC year from the Solar & Lunar Returns API computed fixture
First return chart in the requested UTC year. Download SVG ↗
INSPECT BEFORE SUBSCRIBING

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.

Request JSON POST /v1/astrology/returns
{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  },
  "body": "sun",
  "year": 2026
}
Response JSON · selected fields
{
  "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 ↗

YOUR PRODUCT, YOUR EXPERIENCE

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.

KNOW THE CONVENTIONS

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 ↗

PREDICTABLE ACCESS

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.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

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.

DEVELOPER QUESTIONS

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.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API