--- title: "Natal Chart — Janam Kundali" method: POST path: "/v1/astro/natal" tags: ["Astrology"] --- # Natal Chart — Janam Kundali `POST /v1/astro/natal` ## Request - Base URL: `https://api.asterwise.com` - URL: `https://api.asterwise.com/v1/astro/natal` - Auth: HTTP bearer Calculate a complete Vedic natal chart using Swiss Ephemeris. Returns planet positions in sidereal zodiac, house placements (whole sign), ascendant, nakshatra data, Avakahada Chakra table, and optional classical Vedic interpretation for each planet placement. Also known as Janam Kundali or Janma Kundali. Returns planets (Grahas), houses (Bhavas), ascendant (Lagna), nakshatra positions, and avakahada table. ## Request body - NatalRequest - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required. - `name` string: Person name associated with the birth record - `date` string, required: Birth date in YYYY-MM-DD format - `time` string, nullable: Birth time in HH:MM 24-hour format. If omitted, sunrise chart is used as fallback. - `latitude` number, nullable: Latitude. Required if location not provided. - `longitude` number, nullable: Longitude. Required if location not provided. - `timezone` string, nullable: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used. - `utc_offset` string, nullable: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent. - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations - `include_interpretation` boolean: Whether to include planet-in-house interpretation layer ## Response `200` Natal chart with planetary and house positions - ApiResponseNatalResponse - `success` boolean: True if the request succeeded - `message` string: Human-readable status message - `data` NatalResponse, required - `planets` PlanetPosition[], required: Computed planetary positions - `planet` string, required: Planet name - `sign` string, required: Zodiac sign name where the planet is placed - `sign_num` integer, required: Zero-based zodiac sign index - `degree` number, required: Sidereal longitude in degrees - `nakshatra` string, required: Nakshatra name for planetary placement - `nakshatra_pada` integer, required: Nakshatra pada index - `is_retrograde` boolean, required: Whether the planet is retrograde - `is_combust` boolean: True if the planet is within its combustion orb of the Sun - `is_deep_combust` boolean: True if within 3° of the Sun (deep combustion / Gadha Moudhya) - `house` integer, required: Whole-sign (Rasi) house number where the planet is placed - `rasi_house` integer, nullable: Same as `house` when present (explicit Rasi / whole-sign house) - `bhava_chalit_house` integer, nullable: Bhava Chalit spatial house (1–12) when computed from Bhava Sandhi - `house_system_note` string, nullable: Guidance on Rashi vs Bhava Chalit house placement when the two systems disagree for this planet. - `tropical_longitude` number, nullable: Same position in the tropical zodiac: sidereal longitude plus the ayanamsa at that instant. Only the label changes; houses and every rule stay sidereal. - `tropical_sign` string, nullable: Tropical sign name in English (Aries … Pisces), for Western-style labels. - `tropical_sign_index` integer, nullable: Tropical sign index, 0 = Aries … 11 = Pisces. - `houses` HouseData[], required: Computed house cusp placements - `house` integer, required: House number in the natal chart - `sign` string, required: Sign occupying the house cusp - `sign_num` integer, required: Zero-based zodiac sign index for house cusp - `degree` number, required: House cusp degree within sign - `ascendant` number, required: Ascendant longitude in degrees - `ascendant_sign` string, required: Ascendant sign name - `ayanamsa_value` number, required: Numerical ayanamsa value used in calculations - `ayanamsa_used` string, required: Ayanamsa mode used for the chart - `birth_moment` BirthMoment - `utc` string, required: The birth instant the chart was computed for, in UTC (ISO 8601, to the second). - `utc_offset` string, required: UTC offset applied to the local birth time, as ±HH:MM or ±HH:MM:SS. - `offset_basis` 'iana' | 'local_mean_time' | 'explicit_offset', required: Where the offset came from: the IANA time zone; the birthplace's local mean time (longitude / 15 hours), used for dates before the zone adopted a standard time; or the explicit utc_offset input. - `local_time_status` 'ok' | 'nonexistent' | 'ambiguous', required: 'nonexistent': the local time fell in a daylight-saving gap and was read with the offset in force before the change (moved forward by the gap). 'ambiguous': the local time occurred twice and the first occurrence was used. 'ok' otherwise. - `birth_time_provided` boolean: Whether a precise birth time was provided. False when birth time was not supplied or treated as unknown — calculations using this field will have lagna-dependent accuracy limits. - `interpretation` object[], nullable: Interpretation layer for planetary placements when requested - `ascendant_sign_interpretation` object, nullable: Interpretation details for ascendant sign when interpretation is requested - `moon_sign` string, nullable: Moon's rashi (Sanskrit sign name), same as the Moon entry in planets - `moon_nakshatra` string, nullable: Moon's nakshatra name, same as the Moon entry in planets - `moon_sign_interpretation` object, nullable: Interpretation details for Moon sign when interpretation is requested - `moon_nakshatra_interpretation` object, nullable: Interpretation details for Moon nakshatra when interpretation is requested - `avakahada` object, nullable: Standard Avakahada Chakra details derived from Moon nakshatra and sign - `bhava_madhya` BhavaMadhyaEntry[], nullable: House midpoint (Bhava Madhya) positions — ecliptic longitude with sign and house label. - `house` integer, required: House number 1-12 - `sign` string, required: Sanskrit sign name - `sign_num` integer, required: Sign index 0-11 - `degree` number, required: Ecliptic longitude in degrees - `bhava_sandhi` BhavaMadhyaEntry[], nullable: House junction (Bhava Sandhi) positions — ecliptic longitude with sign and house label. - `house` integer, required: House number 1-12 - `sign` string, required: Sanskrit sign name - `sign_num` integer, required: Sign index 0-11 - `degree` number, required: Ecliptic longitude in degrees - `graha_drishti` object, nullable: Graha Drishti matrix (#143): each graha → map of aspected whole-sign house (1–12) to strength percent (25–100). - `rashi_drishti` RashiDrishtiEntry[], nullable: Jaimini Rashi Drishti aspect pairs — each entry is one active sign-to-sign aspect. - `from_sign` string, required: Aspecting sign (Sanskrit) - `from_sign_num` integer, required: Aspecting sign index 0-11 - `to_sign` string, required: Aspected sign (Sanskrit) - `to_sign_num` integer, required: Aspected sign index 0-11 - `arudha_padas` object, nullable: Arudha A1–A12 (#141): each pada → sign_index and sign_name. - `upapada_lagna` UpapadaLagna: Upapada Lagna (#142): Arudha of 12th house plus 2nd-from-Upapada analysis. - `sign_index` integer, required: Upapada Lagna sign index 0–11 - `sign_name` string, required: Sanskrit sign name of Upapada Lagna - `upapada_lord` string, required: Lord of the Upapada sign - `second_from_upapada_sign_index` integer, required: Sign index 0–11 of the sign second from Upapada Lagna - `second_from_upapada_sign_name` string, nullable: Sanskrit sign name of the second from Upapada Lagna. - `planets_in_second_from_upapada` string[]: Grahas occupying the sign second from Upapada - `has_benefic_in_second_from_upapada` boolean, required: True if a benefic occupies the 2nd-from-Upapada sign - `has_malefic_in_second_from_upapada` boolean, required: True if a malefic occupies the 2nd-from-Upapada sign - `ascendant_tropical_longitude` number, nullable: Ascendant in the tropical zodiac (sidereal longitude plus ayanamsa). - `ascendant_tropical_sign` string, nullable: Tropical sign of the Ascendant, English name. - `ascendant_tropical_sign_index` integer, nullable - `moon_tropical_sign` string, nullable: Tropical sign of the natal Moon, English name. The sidereal moon_sign and every Moon-based rule are unchanged. ## Other responses - `401`: Authentication failed - `403`: Authorization failed - `404`: Resource not found - `413`: Payload too large - `422`: Validation error - `429`: Rate limit exceeded - `500`: Internal error - `502`: Upstream provider error - `503`: Service unavailable --- [API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)