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 ten 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.astroapi.io/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,
"zodiac": "tropical"
}Options: house_system is equal (default), whole_sign, or beta placidus; theme is light (default) or dark; show_aspects defaults to true. The zodiac defaults to tropical. Sidereal requests accept ayanamsa as lahiri (default), raman, or krishnamurti.
The JSON response has type: "natal_svg", status: "beta", svg, house_system, theme, zodiac, ayanamsa, and metadata. Use response.svg, not response.chart. This is an original 1200×1100 Western natal wheel with ten planets, angles, houses, sign labels and optional major aspects. It is not a synastry overlay, Indian chart layout, PNG, 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. Undefined polar-domain geometry returns 400 with no silent substitution. Choose Equal or Whole Sign explicitly if that is appropriate to your application. The existing houses endpoint also accepts system: "placidus"; default birth-chart houses remain unchanged.
Divisional charts: D1, D3, D4, D7, D9, D10 and D12
POST https://api.astroapi.io/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 integers 1, 3, 4, 7, 9, 10 and 12; the default remains 9. For example, set division: 7 in the request above for Saptamsa. This endpoint is always sidereal; do not send a zodiac field. Ayanamsa choices are Lahiri, Raman and Krishnamurti. 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.
- 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.
- 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.
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. These are bounded Parashari mappings, not every variant or D2–D60 coverage as a whole. Practitioner sign-off remains unfinished.
Vimshottari major and subperiods
POST https://api.astroapi.io/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 adds Pratyantardasha. Depths beyond three, 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.astroapi.io/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 Lahiri (default), Raman or Krishnamurti applied at the midpoint date. 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.astroapi.io/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 Lahiri (default), Raman or Krishnamurti. 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.astroapi.io/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 with Lahiri default; Raman and Krishnamurti are also accepted. 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.astroapi.io/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.astroapi.io/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",
"ayanamsa": "lahiri"
}Render original fixed-house North Indian or fixed-sign South Indian layouts for D1, D3, D4, D7, D9, D10 and D12. 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" or theme: "light" explicitly when wanted.
The beta JSON response contains svg, layout, theme, chart (the unchanged Vargas response) and renderer metadata. The original 1200×1420 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 ASTROAPI_KEY supplied through your environment. It makes one D9 request.
// Node.js 22+ — server-side only
const key = process.env.ASTROAPI_KEY;
if (!key) throw new Error("Set ASTROAPI_KEY in your server environment");
const response = await fetch("https://api.astroapi.io/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(`AstroAPI 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 ASTROAPI_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.astroapi.io/api/astro/vargas",
data=json.dumps(payload).encode("utf-8"),
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['ASTROAPI_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' "$ASTROAPI_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.astroapi.io/api/astro/vargasMean and osculating lunar nodes
POST https://api.astroapi.io/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 supports Lahiri (default), Raman and Krishnamurti using the exact identifiers documented above.
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 mean 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.astroapi.io/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 three 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 mean 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.
True solar-arc directions
POST https://api.astroapi.io/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 maps each elapsed model year to one TT ephemeris day. The direct true solar arc is the forward movement of the unrounded apparent tropical Sun from birth to that progressed instant. This is not a fixed one-degree-per-year or Naibod direction.
The same arc rotates the ten natal planets, Ascendant and MC. Tropical is default; sidereal supports the three 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. Full 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 directed nodes, speeds, aspects, Placidus, relocation, interpretation or predictive certainty is supplied.
Vimshottari Pratyantardasha: optional third level
{
"birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
"ayanamsa": "lahiri",
"depth": 3
}Use the existing /api/astro/vimshottari endpoint with integer depth: 3. Every one of the 81 antardashas gains nine subperiods, for 729 Pratyantardasha leaves within the same nine-major-period cycle. Each child sequence starts with its parent lord and divides the parent duration in the existing lord-year proportions. Integer-microsecond arithmetic keeps adjacent intervals contiguous and inside their parent.
Read periods[i].subperiods[j].subperiods[k] and birth_balance.pratyantardasha_lord; input.depth and metadata identify the opt-in third level. The natal Moon, first-period balance, 365.25-day years, half-open intervals and derived-date policy are unchanged. The default two-level JSON is unchanged, including when depth: 2 is explicit. Only integer 2 and 3 are accepted; strings, booleans, nulls and deeper values return 400. This remains one standard request, not 729 billed requests.
Errors and integration safety
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 three documented ayanamsas. Tests of arithmetic and numerical references are not specialist approval of every tradition or evidence of predictive validity. Regional calendars and festivals, compatibility matching scores, strength systems, other house systems, generated reports and general event-search services remain separate, unfinished work.