Chart graphics, Western and Vedic calculations

Beta: these are deterministic calculation tools, not predictions or a complete Jyotish system. Check the declared conventions with your practitioners before using the results in client reports.

All twelve endpoints use POST, JSON, and your server-side API key. Each admitted attempt uses one standard request from your existing plan, including failed calculations. No new plan or overage charge is introduced. API responses are private and no-store; these operations do not save birth profiles or reports.

Shared birth input

{
  "birth": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 40.7128,
    "lon": -74.006
  }
}

Date and time are required strings: YYYY-MM-DD and HH:MM[:SS]. Dates run from 1900-01-01 through 2050-12-31, inclusive. Coordinates must be finite JSON numbers, not strings. Omitted timezone means UTC; ambiguous or nonexistent local clock-change times return 400, so send the known UTC instant instead. Unknown fields, explicit null values, and unsupported option names are rejected. Geographic poles and undefined Ascendant geometry are not accepted.

Natal-chart SVG

POST https://api.cosmicephemeris.com/api/astro/natal-svg

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
  "house_system": "placidus",
  "theme": "dark",
  "show_aspects": true,
  "aspect_profile": "extended",
  "additional_points": ["vertex", "lot_of_fortune", "lot_of_spirit"],
  "include_png": true,
  "zodiac": "tropical"
}

Options: house_system is equal (default), whole_sign, beta placidus, beta porphyry, beta meridian, beta campanus, beta regiomontanus, beta alcabitius, beta koch, beta morinus, beta topocentric, beta sripati, beta vehlow, beta horizon, beta krusinski, beta sunshine, beta sunshine_alt, beta savard, beta pullen_sd, beta pullen_sr, beta carter, beta apc, beta equal_mc, or beta natural; theme is light (default), dark, or monochrome; show_aspects defaults to true. Monochrome is a fixed grayscale, printer-friendly palette—not an accessibility certification. Optional aspect_profile accepts major, standard, or extended; alternatively send a mutually exclusive custom aspects list with unique names and 0.1°–10.0° orbs. Omit both for the original major-only SVG. The optional additional_points array accepts one through six unique exact names: vertex, antivertex, equatorial_ascendant, equatorial_descendant, lot_of_fortune, and lot_of_spirit. Set strict boolean include_png: true to include deterministic PNG bytes; omission or false preserves the SVG-only response. The zodiac defaults to tropical. Sidereal requests accept the eleven documented ayanamsas; omission defaults to lahiri.

The JSON response has type: "natal_svg", status: "beta", svg, house_system, theme, zodiac, ayanamsa, and metadata; explicit aspects add aspect_configuration, while a selected point layer adds a separate additional_points object. With include_png: true, response.png.base64 contains the 1200×1100 raster plus decoded byte count, dimensions, PNG SHA-256 and exact source-SVG SHA-256. The SVG remains present and authoritative. This is an original Western natal wheel with ten planets, angles, houses, sign labels, selected aspect geometry, and only explicitly selected additional-point markers. It is not a synastry overlay, Indian chart layout, PDF or hosted widget.

SVG output is capped at 128 KiB and contains no scripts, remote resources or user-authored markup. Save it server-side and display it as an image; do not use arbitrary response text as page HTML. Very crowded labels return 400 rather than an unreadable chart. There is no URL-fetching or uploaded-chart option.

Placidus uses a bounded semiarc solver. Porphyry divides each ecliptic quadrant between the Ascendant, IC, Descendant and Midheaven into thirds. Meridian divides right ascension into twelve equal arcs from RAMC and projects them onto the ecliptic; cusp 10 is the Midheaven and cusp 1 is the Equatorial Ascendant, not the physical Ascendant. Campanus divides the prime vertical into twelve equal arcs and projects great circles through each division and the north/south horizon points onto the ecliptic. Regiomontanus instead divides the celestial equator into twelve equal arcs and projects great circles through those divisions and the same horizon points. Alcabitius trisects the upper and lower right-ascension arcs anchored by the physical Ascendant and projects those divisions onto the ecliptic along hour circles. Koch trisects the natal Midheaven degree's birthplace rising-to-culmination semiarc and uses intermediate physical Ascendants. Morinus transforms twelve equally spaced celestial-equator points anchored at RAMC directly into ecliptic longitude; its cusps 1 and 10 are not the physical Ascendant and Midheaven. Topocentric uses the Polich/Page trisected-tangent pole heights, with the physical Ascendant and Midheaven as cusps 1 and 10; it changes house geometry only, not planet positions. Sripati moves every cusp to the forward midpoint of the preceding Porphyry sector; its cusps 1 and 10 are not the physical angles. Vehlow uses equal 30-degree ecliptic houses from cusp 1 at Ascendant minus 15 degrees, placing the Ascendant at the center of house 1 while MC remains separate. Horizon/Azimuth projects twelve equal local-horizon divisions through vertical circles to the ecliptic; cusp 1 is the prime-vertical intersection rather than the physical Ascendant, and cusp 10 is MC. Krusinski-Pisa-Goelzer projects twelve equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine alternative independently uses the Makransky prime-vertical projection for the same solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical Ascendant and Midheaven and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is generally not the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural fixes cusp 1 at zero degrees Aries in the selected zodiac and places all cusps on sign boundaries; physical angles remain separate. Campanus, Regiomontanus, Alcabitius, and Koch use the Midheaven as cusp 10 and physical Ascendant as cusp 1. Undefined response geometry returns 400 with no silent substitution. Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, and Natural are not admitted by saved profiles or other chart/report routes in this release. Choose Equal or Whole Sign explicitly if that is appropriate to your application. The existing houses endpoint accepts the same systems; default birth-chart houses remain unchanged.

Vertex is the western prime-vertical/ecliptic intersection; Antivertex is opposite. “Equatorial Ascendant” is used instead of the ambiguous “East Point” label and means the Ascendant at latitude zero. Fortune and Spirit use explicit day/night formulas, with sect determined by the apparent Sun center above or below the geometric horizon. These points are calculated symbols, not planets, and include no interpretation.

Twenty-four divisional charts through D150

POST https://api.cosmicephemeris.com/api/astro/vargas

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
  "ayanamsa": "lahiri",
  "division": 9
}

division accepts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 16, 20, 24, 27, 30, 40, 45, 60, 81, 108, 144, and 150; the default remains 9. This endpoint is always sidereal; do not send a zodiac field. Ayanamsa choices are Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, and Galactic Alignment/Mardyks. Classification uses unrounded sidereal longitudes.

The response includes type: "vargas", status: "beta", division, normalized input, birth_utc, ascendant, bodies, and convention metadata. Each point identifies its source sidereal longitude, divisional longitude, sign, degree within sign and division index. Rahu/Ketu are mean nodes; these are sign placements, not a full dignity, strength or interpretation analysis.

D1 retains the source sidereal sign and longitude.
D2 Hora uses Sun/Leo then Moon/Cancer in odd signs and reverses the order in even signs.
D3 Drekkana uses three equal parts, assigned to the source sign, fifth and ninth.
D4 Chaturthamsa uses four equal parts, assigned to the source sign, fourth, seventh and tenth.
D5 Panchamsha uses the fixed P.V.R. odd sequence Aries, Aquarius, Sagittarius, Gemini, Libra and even sequence Taurus, Virgo, Pisces, Capricorn, Scorpio.
D6 Shashthamsha uses six five-degree parts; odd signs count forward from Aries and even signs count forward from Libra.
D8 Ashtamsha uses eight 3°45′ parts; movable signs count from Aries, fixed signs from Sagittarius and dual signs from Leo.
D11 Rudramsha divides each source sign into eleven exact parts; its start is found by counting the source-sign ordinal anti-zodiacally from Aries, then parts advance zodiacally.
D7 Saptamsa uses seven equal parts; odd-numbered signs start from themselves, even-numbered signs from the seventh, then count forward.
D9 divides each sign into nine parts; movable signs start from themselves, fixed signs from the ninth, dual signs from the fifth.
D10 divides each sign into ten parts; odd-numbered signs start from themselves, even-numbered signs from the ninth.
D12 Dwadasamsa uses twelve equal parts, starting from the source sign and counting forward.
D16 Shodasamsa uses sixteen equal parts with movable, fixed, and dual sign starts.
D20 Vimsamsa uses twenty equal parts with movable, fixed, and dual sign starts.
D24 Chaturvimsamsa uses twenty-four equal parts with different odd/even sign starts.
D27 Bhamsa uses twenty-seven equal parts with fire, earth, air, and water sign starts.
D30 Trimsamsa uses the documented unequal Parashari segments for odd and even signs.
D40 Khavedamsha uses forty equal parts, beginning from Aries for odd signs and Libra for even signs.
D45 Akshavedamsha uses forty-five equal parts, beginning from Aries, Leo, or Sagittarius for movable, fixed, or dual signs.
D60 Shashtiamsa uses sixty half-degree parts counted from the source sign.
D81 Navanavamsha is the direct 81-part harmonic equivalent to applying the admitted D9 mapping twice.
D108 Ashtottaramsa compounds the admitted D9 then D12 mappings.
D144 Dwadas-Dwadasamsa applies the admitted D12 mapping twice.
D150 Nadiamsa defaults to the P.V.R./JHora own-sign uniform-direct mapping and accepts only the seven other exact method identifiers documented in OpenAPI.

Boundaries belong to the following part. Within-part progress is scaled linearly into the assigned sign; this is an explicit degree convention in addition to the traditional sign assignment. D7 uses exact equal sevenths, not truncated arcsecond boundaries. D30 uses unequal segments and D60 uses the source-sign-plus-part convention documented in the response metadata. These are bounded named mappings, not every possible divisional chart or alternative lineage. Practitioner sign-off remains unfinished.

Vimshottari major and subperiods

POST https://api.cosmicephemeris.com/api/astro/vimshottari

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
  "ayanamsa": "lahiri"
}

The Moon's unrounded sidereal longitude determines the natal nakshatra, starting lord and birth balance. The fixed lord sequence is Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury, with durations 7, 20, 6, 10, 7, 18, 16, 19 and 17 years. Each year is exactly 365.25 days in this implementation; results differ from traditions using another year length.

The response includes type: "vimshottari", status: "beta", normalized input, birth_utc, moon, birth_balance, cycle, periods and metadata. It returns one complete theoretical 120-year cycle starting at the beginning of the major period active at birth, not a fresh 120 years counted forward from birth. There are nine major periods, each with nine subperiods.

Intervals are half-open: start_utc <= instant < end_utc. The first major period and some subperiods can precede birth. Derived period timestamps may extend outside the 1900–2050 input window: they are arithmetic dates, not ephemeris extrapolation. Omitted depth or depth: 2 keeps this original two-level response unchanged. Optional depth: 3 and depth: 4 add Pratyantardasha and Sookshma levels. Depths beyond four, alternate year lengths and other dasha systems are not supported.

Davison relationship chart

Beta: an uncorrected TT/arithmetic physical time-and-place midpoint chart, separate from the symbolic midpoint composite.

POST https://api.cosmicephemeris.com/api/astro/davison

{
  "personA": {"date":"2000-01-01","time":"12:00","lat":40,"lon":-74},
  "personB": {"date":"2000-01-03","time":"12:00","lat":50,"lon":2}
}

Read midpoint.utc, midpoint.location, planets, angles, houses and aspects. This example gives 2000-01-02 12:00 UTC, latitude 45 and longitude -36. Node uses api.davison(input); Python uses api.davison(input).

The named method is uncorrected_tt_arithmetic: average uniform TT instants, including recorded leap seconds, then calculate the sky at the arithmetic mean coordinates. Longitude +180 is canonicalized to -180 before averaging; 170 and -170 therefore average to 0, not the date line. This is not a spherical midpoint or MC-corrected Davison. UTC output can include second 60; preserve it as a string. midpoint.tt_jd is display-only.

Both birth times and numeric coordinates are required, with the existing 1900–2050 civil-date and DST rules. Optional zodiac is tropical (default) or sidereal, with one of the eleven documented ayanamsas applied at the midpoint date; omission defaults to Lahiri. house_system accepts Equal (default) or Whole Sign; their JSON values are equal and whole_sign. No nodes, relocation, corrected/spherical variant, Placidus or interpretations. One standard quota unit per admitted attempt; no automatic retries. Practitioner acceptance remains open.

Midpoint composite

POST https://api.cosmicephemeris.com/api/astro/composite

{
  "personA": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0,
    "lon": 0
  },
  "personB": {
    "date": "1990-06-15",
    "time": "08:30",
    "timezone": "Asia/Kolkata",
    "lat": 28.6139,
    "lon": 77.209
  },
  "zodiac": "tropical",
  "house_system": "equal"
}

This is a symbolic shortest-arc midpoint chart for two known birth times, not the sky at a physical place or a Davison chart. Tropical is default; sidereal accepts the eleven documented ayanamsas and defaults to Lahiri. Each source uses its own date-aware ayanamsa before the midpoint. Planet, Ascendant and MC longitudes use independent shortest arcs. Antipodal points within 1e-10 degrees return 400 because the midpoint is ambiguous; there are no arbitrary 180-degree inner-planet flips.

Read planets, angles, houses, aspects and metadata from the beta JSON response. Houses are explicitly synthetic Equal (default) or Whole Sign from the midpoint Ascendant, not geographically solved houses. No Placidus, nodes, speeds or interpretation option is offered. Aspects use the existing natal longitude orbs.

Panchang at a specified instant

POST https://api.cosmicephemeris.com/api/astro/panchang

{
  "at": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "Asia/Kolkata",
    "lat": 28.6139,
    "lon": 77.209
  },
  "ayanamsa": "lahiri"
}

The five classifications are tithi, nakshatra, yoga, karana and sunrise-based vara. They are evaluated at your requested instant, not automatically at sunrise. This endpoint is sidereal, accepts the eleven documented ayanamsas, and defaults to Lahiri. Latitude is restricted to inclusive [-88, 88] for the verified beta solar-event domain.

The response returns tithi, nakshatra, yoga, karana, civil weekday, vara, solar_events and explicit metadata. Weekday and vara use Sunday=0 through Saturday=6, but vara begins at sunrise rather than civil midnight. Solar events cover the requested local civil date, using the USNO standard −50 arcminute horizon at elevation 0, not a Hindu-geocentric sunrise convention. Unsupported near-tangent solar candidates return 400 after a geometric crossing check. A solar event inside a recorded leap second also returns 400, because the local civil timestamp cannot represent that second. Polar no-event days return empty arrays and an unavailable vara with null fields; no transit is mislabeled as sunrise. Before sunrise, vara can use the previous civil day when available. Ordinary 23/25-hour DST days are supported; ambiguous/nonexistent midnight boundaries return 400. Historical local event offsets may include seconds, such as +05:21:10; use the paired utc string for interoperable parsing. No festivals, regional calendar, muhurta election or date-range event search is included.

Secondary-progressed planets

POST https://api.cosmicephemeris.com/api/astro/secondary-progressions

{
  "birth": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0,
    "lon": 0
  },
  "target": {
    "date": "2026-09-14",
    "time": "12:00",
    "timezone": "UTC"
  },
  "zodiac": "tropical",
  "house_system": "equal"
}

This day-for-year beta advances the ephemeris by one TT day for each fixed 365.2421904-day year elapsed since birth. It does not count calendar birthdays. Both birth and target date/time are required; target must not precede birth. Tropical/Equal natal context are default; sidereal and Whole Sign are explicit options.

Read progressed_planets for the ten progressed planetary longitudes. natal_context contains separately labeled natal planets, angles and houses, not progressed angles or houses. The response includes birth_utc, target_utc, progressed_utc, timing and convention metadata. A derived instant can land in a recorded leap second: progressed_utc may contain second 60, which JavaScript Date and Python datetime cannot parse directly. Preserve this string; the TT Julian date is a display/reference field, not a claim of arbitrary precision. No progressed angles, progressed houses, aspects, nodes, speeds, relocation or predictions are returned.

North and South Indian chart SVGs

POST https://api.cosmicephemeris.com/api/astro/varga-svg

{
  "birth": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0,
    "lon": 0
  },
  "division": 1,
  "layout": "north_indian",
  "theme": "dark",
  "include_png": true,
  "ayanamsa": "lahiri"
}

Render original fixed-house North Indian or fixed-sign South Indian layouts for all twenty-four supported divisions: D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D16, D20, D24, D27, D30, D40, D45, D60, D81, D108, D144, and D150. Defaults are division: 1, layout: "north_indian", theme: "dark" and Lahiri. Note the D1 default differs from the D9 default of /vargas. Set layout: "south_indian", theme: "light", or theme: "monochrome" explicitly when wanted.

D150 is live with eight exact named mappings. Omission preserves pvr_jhora_own_sign_uniform_direct. Explicit d150_method may instead select deva_keralam_chandra_kala_nadi_non_uniform, deva_keralam_chandra_kala_nadi_uniform_direct, parivritti_cyclic, movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward, movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward, movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward, or movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward. The field is valid only with division: 150; exact conventions and conditional schemas are in OpenAPI. These bounded alternatives do not imply one universal D150 convention or practitioner acceptance.

The beta JSON response contains svg, layout, theme, chart (the unchanged Vargas response) and renderer metadata. Strict boolean include_png: true additionally returns a deterministic 1200×1420 PNG with byte count and verification hashes; omission or false preserves the SVG-only response. The original SVG uses unrounded Vargas positions, nine traditional bodies including mean Rahu/Ketu, and the divisional Ascendant. Houses count signs from the divisional Ascendant; this is not a bhava-chalit calculation or an interpretation report. SVG is capped at 128 KiB, contains no remote resources or scripts, and accepts no uploaded SVG, chart, image, font or URL. Display saved output as an image.

Node.js 22+ example

Run this as a server-side .mjs file with COSMICEPHEMERIS_KEY supplied through your environment. It makes one D9 request.

// Node.js 22+ — server-side only
const key = process.env.COSMICEPHEMERIS_KEY;
if (!key) throw new Error("Set COSMICEPHEMERIS_KEY in your server environment");
const response = await fetch("https://api.cosmicephemeris.com/api/astro/vargas", {
  method: "POST",
  redirect: "error",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${key}`
  },
  signal: AbortSignal.timeout(20000),
  body: JSON.stringify({
    birth: {date: "2000-01-01", time: "12:00", timezone: "UTC", lat: 40.7128, lon: -74.006},
    ayanamsa: "lahiri",
    division: 9
  })
});
if (!response.ok) throw new Error(`Cosmic Ephemeris HTTP ${response.status}`);
const data = await response.json();
console.log(data.bodies);

Python example

This standard-library example needs no third-party package. Run it on your server with COSMICEPHEMERIS_KEY in the environment. Its 20-second timeout limits socket inactivity, not total elapsed time: DNS or a slow stream can take longer. Production applications should also enforce an overall job deadline.

# Python 3.10+ — server-side only
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler, ProxyHandler

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, request, file, code, message, headers, new_url):
        return None

payload = {
    "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
    "ayanamsa": "lahiri",
    "division": 9
}
request = Request(
    "https://api.cosmicephemeris.com/api/astro/vargas",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['COSMICEPHEMERIS_KEY']}"
    },
    method="POST"
)
# Redirects fail instead of forwarding your private header to another URL.
opener = build_opener(ProxyHandler({}), NoRedirect())
with opener.open(request, timeout=20) as response:
    body = response.read(1048577)
    if len(body) > 1048576:
        raise ValueError("Unexpectedly large API response")
    result = json.loads(body)
print(result["bodies"])

cURL example

Use a trusted terminal with shell tracing disabled. This passes the private header on standard input, not as a curl command-line argument. Do not add a redirect-following option.

printf 'Authorization: Bearer %s\n' "$COSMICEPHEMERIS_KEY" | curl --disable \
  --fail-with-body --silent --show-error --max-time 20 --proto '=https' \
  --header @- --header 'Content-Type: application/json' \
  --data '{"birth":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":40.7128,"lon":-74.006},"ayanamsa":"lahiri","division":9}' \
  https://api.cosmicephemeris.com/api/astro/vargas

Mean and osculating lunar nodes

POST https://api.cosmicephemeris.com/api/astro/lunar-nodes

{
  "at": {"date": "2026-09-14", "time": "12:00", "timezone": "UTC"},
  "zodiac": "sidereal",
  "ayanamsa": "lahiri"
}

This beta accepts one at civil instant with required date/time and optional timezone. It is geocentric and accepts no latitude or longitude. Tropical is the default; sidereal accepts the eleven documented ayanamsas and defaults to Lahiri.

Read mean.north, mean.south, true.north and true.south. Each point contains longitude, sign, deg_in_sign and tropical_longitude. The mean model uses the existing Meeus mean-node polynomial in mean ecliptic/equinox-of-date axes. The separate true model intersects the instantaneous geometric DE421 Moon–Earth orbital plane with the date ecliptic, in true ecliptic/equinox-of-date axes. Model/frame fields describe those tropical source axes before sidereal subtraction. This geometric calculation applies no light time or aberration; the sidereal true model retains nutation under the existing date-aware ayanamsa convention.

The response identifies type: "lunar_nodes", status: "beta", the normalized instant and explicit method metadata. Four decimal degrees describe output resolution, not an accuracy guarantee. An osculating node is one instantaneous orbital model, not a universal true-node convention or an eclipse/event prediction. Legacy chart nodes.true still equals the mean node, and timeline Rahu/Ketu still use mean nodes.

Next solar or lunar return

POST https://api.cosmicephemeris.com/api/astro/returns

{
  "birth": {"date": "1990-01-01", "time": "12:00", "timezone": "America/New_York", "lat": 40.7128, "lon": -74.006},
  "body": "sun",
  "after": {"date": "2026-09-14", "time": "12:00", "timezone": "UTC"},
  "zodiac": "tropical",
  "house_system": "equal"
}

Required fields are birth, body (sun or moon) and after with date/time and optional timezone. This finds the first forward crossing of the body's unrounded natal longitude beyond after plus a fixed one-millisecond exclusion. A root inside that exclusion counts as the current return and the search selects the next cycle. The search instant may precede birth. Tropical and Equal houses are defaults; sidereal accepts the eleven ayanamsas and return houses support equal or whole_sign. Optional location: {lat, lon} sets return-chart coordinates; omission uses the birth location. Location affects houses and angles, not the geocentric return time.

The complete fixed search window—370 TT days for the Sun or 32 for the Moon—must fit inside the supported UTC range from 1900 through 2050. Requests near the upper date boundary can therefore return 400 even when their submitted dates are valid. Windows are never clipped. Coarse steps are fixed at two days for the Sun and six hours for the Moon; bounded bisection then requires a bracket no wider than 0.001 seconds and a longitude residual no larger than 1e-7 degrees. These are numerical tolerances, not physical accuracy promises. Arbitrary bodies, horizons, sampling, target longitudes and tolerances are unsupported.

Read return_utc, natal_longitude_deg, return_longitude_deg, chart, search and metadata from the type: "returns", status: "beta" response. The physical chart uses the solved instant and selected location, with existing chart serialization, aspect orbs and mean-node fields. Sidereal comparison applies each ephemeris date.s own selected ayanamsa with nutation retained. Preserve return_utc as a string: a recorded leap second can contain second 60. No interpretation, progressed houses or general event-search service is included.

Named solar-arc directions

POST https://api.cosmicephemeris.com/api/astro/solar-arcs

{
  "birth": {"date": "1990-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
  "target": {"date": "2026-09-14", "time": "12:00", "timezone": "UTC"},
  "zodiac": "tropical",
  "house_system": "equal"
}

Supply a known birth and target; the target must not precede birth. The same fixed 365.2421904-day year defines elapsed model years. Omitted method and exact true_solar_arc preserve the predecessor response: the forward movement of the unrounded apparent tropical Sun from birth to the progressed instant. Exact method: "mean_naibod" is a separate direct longitude convention that multiplies elapsed model years by exactly 0.98564733°; it does not sample a progressed Sun.

The same arc rotates the ten natal planets, Ascendant and MC. Tropical is default; sidereal supports the eleven documented ayanamsas and rotates natal sidereal positions by that same tropical arc. It uses the natal-date ayanamsa, not a progressed- or target-date sidereal Sun difference. Equal houses are rebuilt from the directed Ascendant; Whole Sign begins at its sign boundary. MC is independent of cusp ten. These are synthetic directions, not the sky at a physical event, and are separate from secondary-progressed planets and return charts.

Read arc, directed_planets, directed_angles and directed_houses, with the original points in natal_context and the day-for-year mapping in timing. The true-Sun arc includes natal/progressed Sun longitudes; the mean-Naibod arc instead includes key_degrees_per_year. Full conditional fields and method metadata are defined in OpenAPI. Inputs retain the 1900–2050 civil-date boundary and strict calendar, coordinate and DST validation. Work is bounded by the supported elapsed span, not a caller-selected search window. Preserve derived UTC timestamps as strings because recorded leap seconds can contain second 60. No converse or right-ascension direction, MC-derived angle recalculation, arbitrary key, directed nodes, speeds, aspects, Placidus, relocation, interpretation or predictive certainty is supplied. The mean-Naibod candidate remains beta and awaits fresh practitioner review.

Vimshottari: optional third and fourth levels

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
  "ayanamsa": "lahiri",
  "depth": 3
}

Use integer depth: 3 for the unchanged 729 Pratyantardashas. Use depth: 4 to subdivide every Pratyantardasha once more into nine Sookshma periods: exactly 6,561 fourth-level leaves within the same nine-major-period cycle. Each fixed child sequence begins with its parent lord and uses the same proportional lord weights. Integer-microsecond arithmetic keeps adjacent intervals contiguous and inside their parent.

Depth four adds periods[i].subperiods[j].subperiods[k].subperiods, birth_balance.sookshma_dasha_lord, and exact level/count metadata. Each fourth-level leaf has lord, start_utc, end_utc, and active_at_birth; its redundant display-only years field is omitted so the complete response remains below the existing 1 MiB ceiling. The default/explicit-two JSON and complete depth-three JSON are unchanged. Only integers 2, 3, and 4 are accepted. Depth four is synchronous-only because durable jobs retain a 256 KiB result cap. A synchronous call remains one standard request, not 6,561 billed requests.

Directional Ashtakoota scores

POST https://api.cosmicephemeris.com/api/astro/ashtakoota

Supply strict groom and bride birth objects dated from 1900-01-01 through 2050-12-31, plus optional Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, or Galactic Alignment/Mardyks ayanamsa. The roles are explicit and directional: reversing them can change asymmetric components. The calculation is always sidereal and uses the versioned Saravali/Maitreya table set.

Read the eight component entries in kootas, the unrounded component arithmetic, and total out of 36. This bounded beta supplies no pass/fail threshold, dosha cancellation, remedy, medical claim, relationship advice, generated interpretation, or claim of practitioner acceptance. Full request and response examples are in OpenAPI and Postman.

Ashtakavarga tables and optional reductions

POST https://api.cosmicephemeris.com/api/astro/ashtakavarga

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 0, "lon": 0},
  "ayanamsa": "lahiri",
  "include_reductions": true
}

This sidereal-only beta accepts the standard strict birth object and any documented ayanamsa, with Lahiri as the default. It applies the versioned BPHS chapter 66 benefic-place tables to the Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, and ascendant. Rahu and Ketu are excluded.

Read the eight contributor rows for each target in prastara, the seven summed rows in bhinnashtakavarga, and the zodiac-sign and ascendant-house views in sarvashtakavarga. The invariant planet totals are 48, 49, 39, 54, 56, 52, and 39; their Sarvashtakavarga total is 337. Omit include_reductions to preserve the original response. Exact JSON true additionally returns transparent BPHS chapters 67–69 Trikona and Ekadhipatya rows plus Rashi, Graha, and Shodhya pindas. The reduced convenience sum is explicitly not labeled classical Sarvashtakavarga. Transit scoring, interpretations, rankings, remedies, and predictions remain excluded; fresh practitioner review remains incomplete.

Partial Shadbala foundation

POST https://api.cosmicephemeris.com/api/astro/natal-analysis

{
  "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 0, "lon": 0},
  "points": ["sun", "moon", "mercury"],
  "zodiac": "sidereal",
  "ayanamsa": "lahiri",
  "include_shadbala_foundation": true
}

Exact JSON true adds Uchcha, Rashi/Navamsha Ojhayugma, explicitly whole-sign Kendradi, Drekkana, and Naisargika Virupas for the seven classical grahas. The response is labeled partial_beta, lists every excluded component, and does not return a Shadbala total or strength verdict. Omission or false preserves the existing natal-analysis response. Fresh practitioner review remains incomplete.

Errors and integration safety

All fourteen endpoints on this page are additive beta contracts. Read authentication before calling. Expect 400 for unsupported or undefined calculations, 401 for an invalid key, 429 for quota or per-user concurrency limits, 503 for global admission capacity, and 502/504 for engine failure/timeout. Use a bounded client timeout, inspect the HTTP status, and do not automatically retry charged attempts.

The full request/response schemas are in OpenAPI; runnable requests are in Postman. Calculations reuse the JPL DE421 coordinate model and eleven documented ayanamsas. Tests of arithmetic and numerical references are not specialist approval of every tradition or evidence of predictive validity. Regional calendars and festivals, broader compatibility systems, the remaining Shadbala components, other house systems, generated interpretations and unbounded event-search services remain separate, unfinished work.