Solar return charts via astrology API

Q: How do I find the exact solar return time with the API?

Compute the natal Sun's longitude once via /v2/astrology/planets, then binary-search the day-before-to-day-after window around the birthday for the timestamp where the transiting Sun's longitude matches the natal value. Around 25-30 iterations converges to sub-minute precision.

Q: Can I get a Vedic Varshaphal instead of a Western solar return?

Yes. Set system to vedic for the sidereal annual chart and pull Varshaphal factors such as the Muntha and year-lord from the annual endpoints. The same birth data can produce both a tropical solar return and a sidereal Varshaphal.

A solar return chart is cast for the exact moment the transiting Sun returns to the precise zodiacal longitude it held at birth, marking the start of a new "astrological year." With the Vedika astrology API you generate one by computing a chart for that return instant and interpreting it against the natal chart. This guide walks through finding the return moment, casting the chart through POST /api/v1/astrology/query or the /v2/astrology/* computation endpoints, and structuring an annual reading you can ship in a birthday or year-ahead feature.

What a solar return chart is

The Sun travels roughly one degree per day, so it does not return to its exact natal longitude on your calendar birthday — it lands a few hours to a day either side. The solar return is the instant the Sun's ecliptic longitude exactly equals the natal value. A chart erected for that instant, at a chosen location, becomes the "annual chart" used in predictive work.

The technique appears in both traditions developers integrate through this API. In Western practice the annual ingress chart and its angles are read for the year's themes; the foundational discussion of the Sun's significations and the prorogation of the year traces to Ptolemy's Tetrabiblos. In Vedic practice the equivalent is the Varshaphal or annual Tajaka chart, whose method — Muntha progression, the Tajaka aspects, and the year-lord (Varshesha) — is documented in the Tajaka literature that Jyotish students study. The API exposes both, so a single integration can return a tropical solar return and a sidereal Varshaphal from the same birth data.

Solar return vs. transits vs. progressions

Solar return — one chart per year, recast for the return instant; read as a snapshot of the coming twelve months.
Transits — the moving planets compared to the natal chart on any given day; finer-grained, event-level timing.
Progressions / dashas — symbolic time keys (secondary progressions in Western work, Vimshottari dasha in Vedic) that run continuously rather than resetting annually.

A solid year-ahead feature layers all three; this article focuses on the solar return as the anchor.

Step 1 — Find the exact return instant

You need the moment the transiting Sun matches the natal Sun's longitude. The reliable approach is to compute the natal Sun's longitude first, then search the candidate window (the day before through the day after the birthday in the target year) for the timestamp where the transiting Sun's longitude crosses that value.

Use the V2 computation endpoints for the raw planetary longitudes — they take flat datetime / latitude / longitude / timezone fields and return positions you can iterate over.

curl -X POST https://api.vedika.io/v2/astrology/planets \
  -H "x-api-key: vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-04-18T07:30:00",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": "Asia/Kolkata",
    "system": "western"
  }'

Read the Sun's longitude from that response. Then narrow the return instant with a short binary search across the birthday window. Because the Sun's motion is smooth and monotonic over a two-day span, a handful of iterations converges to sub-minute precision.

import requests

BASE = "https://api.vedika.io"
HEADERS = {"x-api-key": "vk_live_YOUR_KEY", "Content-Type": "application/json"}

def sun_longitude(dt_iso, lat, lon, tz):
    r = requests.post(f"{BASE}/v2/astrology/planets", headers=HEADERS, json={
        "datetime": dt_iso, "latitude": lat, "longitude": lon,
        "timezone": tz, "system": "western",
    })
    r.raise_for_status()
    planets = r.json()["planets"]
    return next(p["longitude"] for p in planets if p["name"] == "Sun")

def find_solar_return(natal_lon, year, lat, lon, tz, birthday="04-18"):
    from datetime import datetime, timedelta
    lo = datetime.fromisoformat(f"{year}-{birthday}T00:00:00") - timedelta(days=1)
    hi = lo + timedelta(days=2)
    for _ in range(28):  # ~sub-minute convergence
        mid = lo + (hi - lo) / 2
        diff = (sun_longitude(mid.isoformat(), lat, lon, tz) - natal_lon + 180) % 360 - 180
        if diff < 0:
            lo = mid
        else:
            hi = mid
    return lo + (hi - lo) / 2

natal = sun_longitude("1990-04-18T07:30:00", 28.6139, 77.2090, "Asia/Kolkata")
return_moment = find_solar_return(natal, 2026, 28.6139, 77.2090, "Asia/Kolkata")
print("Solar return:", return_moment.isoformat())

Two design notes. Cache the natal longitude — it never changes, so compute it once per user. And keep your iteration count modest; the ephemeris is deterministic, so you pay per computation call, not for precision past the minute that matters for a return chart.

Step 2 — Cast the chart for the return moment

The location of a solar return chart is a deliberate choice: the birthplace gives a "natal-anchored" reading, while the user's current residence gives a "relocated" return that many practitioners prefer for the year actually lived. Expose it as a parameter and let the caller decide.

With the return instant and chosen coordinates in hand, request the full chart. The V2 endpoints return houses, angles, and aspects you can compare against the natal chart.

curl -X POST https://api.vedika.io/v2/astrology/chart \
  -H "x-api-key: vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2026-04-18T13:12:00",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": "Asia/Kolkata",
    "system": "western"
  }'

For a Vedic annual chart, switch system to vedic (sidereal) and pull the Varshaphal-specific factors — the Muntha position and year-lord — from the dedicated annual endpoints under /v2/astrology/. Because all three systems live in one API, you can return a tropical solar return and a sidereal Varshaphal for the same birth without a second integration.

Why the chart math holds up

Every position above is computed by XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, published on the major package registries with around 2,200 tests). It has been validated against JPL DE440 and the swetest reference, with zero charts deviating beyond 0.1° across a five-million-chart test run. That is astronomical precision for the planetary longitudes that drive the return moment — interpretation is a separate, sourced layer.

Step 3 — Interpret the return against the natal chart

A solar return is read in relation to the birth chart, not in isolation. The interpretive signal lives in a few comparisons:

The return Ascendant and Midheaven, and which natal house they fall into.
The house the return Sun occupies — a primary theme-setter for the year.
Return planets that conjoin natal angles or natal planets.
In the Vedic chart, the Muntha's house and the year-lord's condition.

You can wire this comparison yourself from the raw V2 output, or hand the natural-language work to Vedika AI through the query endpoint. The AI path takes a question plus structured birth details and returns a grounded reading whose astrological claims are attributable to the classical corpus the system is built on — Brihat Parashara Hora Shastra, Phaladeepika, the Tajaka texts for Varshaphal, and Tetrabiblos for the Western reading.

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Read my solar return for the year ahead, focusing on career and the return Ascendant.",
    "birthDetails": {
      "datetime": "1990-04-18T07:30:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    },
    "speed": "fast"
  }'

The speed: "fast" flag routes to Vedika Swift for lower latency, which suits an interactive birthday widget; drop it for the deeper Vedika Pro Ultra reading in a generated year-ahead report. For a streaming UI, hit POST /api/v1/astrology/query/stream and consume the SSE events token by token.

Bringing the annual report together

Look up and cache the natal Sun longitude once per user.
Compute the solar return instant for the target year (Step 1).
Cast the return chart at the chosen location (Step 2).
Send the question and birth details to the query endpoint for the narrative, or assemble it from raw factors if you want full control of the copy (Step 3).
Localize — the reading can be returned in any of 30 supported languages, including 14 Indic ones.

Pricing and getting started

You can prototype the whole flow against the free sandbox with no key. When you move to production, plans start at $12/mo (Starter) and scale through Professional, Business, and Enterprise; AI queries run roughly $0.01–$0.05 each, so an annual solar-return reading is a fraction of a cent in computation plus one query. See pricing for the current tiers and the fast-path and voice add-ons.

Honest context on alternatives: dedicated Vedic providers like Prokerala offer solid panchang and basic chart data at a low entry price, and AstrologyAPI.com and RoxyAPI cover Western and remedial content well. Where this API differs for a solar-return build is having Vedic, Western, and KP in a single contract, the open-source ephemeris you can audit yourself, and a grounded AI layer that cites the classical texts rather than improvising. Full request and response shapes are in the docs.

Tips for production

Store the natal longitude and the computed return instant; recompute only when the user edits their birth data.
Expose chart location as relocated-vs-birthplace and document which your reading assumes.
Validate timezone strings — a wrong offset shifts the return moment and the return Ascendant.
For automation and assistant integrations, the public MCP server (npx @vedika-io/mcp-server, 36 tools) lets an MCP-compatible client compute charts conversationally.

Key facts

A solar return chart is cast for the instant the transiting Sun returns to its exact natal longitude — typically a few hours off the calendar birthday.
Compute it via /v2/astrology/* for raw positions, then narrow the return instant with a short binary search over the birthday window.
The Vedika API serves Vedic (sidereal), Western (tropical), and KP from one contract, so a tropical solar return and a sidereal Varshaphal come from the same birth data.
Planetary positions are computed by XALEN Ephemeris (Apache-2.0, ~2,200 tests), validated against JPL DE440 and swetest with zero charts beyond 0.1° across a 5M-chart run.
Narrative readings come from POST /api/v1/astrology/query, with claims attributable to BPHS, Phaladeepika, the Tajaka texts, and Tetrabiblos.
Free sandbox, no key; production plans from $12/mo, queries roughly $0.01–$0.05; output available in 30 languages.

FAQ

How do I find the exact solar return time with the API?

Compute the natal Sun's longitude once via /v2/astrology/planets, then binary-search the day-before-to-day-after window around the birthday for the timestamp where the transiting Sun's longitude matches the natal value. Around 25–30 iterations converges to sub-minute precision.

Should the solar return chart use the birthplace or current location?

Both are valid techniques. The birthplace gives a natal-anchored reading; the user's current residence gives a relocated return many practitioners prefer for the year actually lived. Expose it as a parameter and document which your interpretation assumes.

Can I get a Vedic Varshaphal instead of a Western solar return?

Yes. Set system to vedic for the sidereal annual chart and pull Varshaphal factors such as the Muntha and year-lord from the annual endpoints. The same birth data can produce both a tropical solar return and a sidereal Varshaphal.

How accurate are the chart positions?

Planetary longitudes are computed by the open-source XALEN Ephemeris, validated against JPL DE440 and swetest with no chart deviating beyond 0.1° across a five-million-chart test. That is astronomical precision for the math; astrological interpretation is a separate, source-cited layer.

What does a solar-return reading cost?

Prototyping is free in the sandbox. In production, plans start at $12/mo and individual AI queries run about $0.01–$0.05, so a full annual reading is a fraction of a cent of computation plus one query.