/api/astro/western/natal-chart/1 creditWestern natal chart
A tropical natal chart: the same twelve bodies, plus every aspect between them. TROPICAL, not sidereal. Every other chart endpoint here subtracts the ayanamsa — about 24 degrees at present — which moves nearly every planet into the previous sign. Someone born on 15 August is a Leo here and a Cancer on /api/astro/chart/. Both are correct for their own tradition; pick the one your product uses and do not mix them. Twelve bodies: the ten Western planets, the true north node and Chiron. Each returns its longitude, the sign and degrees within it, a formatted position, its daily motion and whether it is retrograde. Send a date, a time and a place. Nothing else — the zodiac is fixed by the route. Aspects cover the five Ptolemaic angles — conjunction, sextile, square, trine, opposition — plus quincunx and semisextile. Each carries its exact angle, the `orb` by which it misses exact, and the `allowed_orb` that admitted it, so you can filter tighter than our defaults without recalculating. `applying` is true while the aspect is still forming and false once it has passed exact, derived from the bodies' own daily motion. Orbs are a matter of convention and astrologers disagree; ours are the widely used defaults and are stated on every hit rather than assumed.
https://yogataraapi.prahlad.app/api/astro/western/natal-chart/Authentication
Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.
X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/jsonRequest fields
| Field | Type | Required | Notes |
|---|---|---|---|
| date_time | string (date-time) | required | The moment to calculate for, ISO 8601. ALWAYS include an offset or a trailing Z - a value with no zone is read as Asia/Kolkata (UTC+05:30), not UTC, and can return the previous day's result with a 200. '2026-09-01T06:00:00Z' and '2026-09-01 06:00:00' are different instants and give different answers. |
| latitude | number (double) | required | Latitude of the place, in decimal degrees. Positive is north, negative is south. Example: 26.9124 for Jaipur, 40.7128 for New York. Minutes and seconds are not accepted - convert first. min -89.9 · max 89.9 |
| longitude | number (double) | required | Longitude of the place, in decimal degrees. Positive is east, negative is west. Example: 75.7873 for Jaipur, -74.0060 for New York. Note the sign: a missing minus puts New York in China. min -180 · max 180 |
| timezone_as_float | number (double) | required | UTC offset of the place, in hours, as a decimal. Example: 5.5 for India (UTC+05:30), -5 for New York in winter, 5.75 for Nepal. This is NOT validated against date_time - if the two disagree you get a successful response for the wrong moment, so derive both from the same source. Use the offset in force on that date, not today's: a summer birth in a country with daylight saving needs the summer offset. min -12 · max 14 |
| keys | array | optional | Which calculations to return, as a list of names. See the key table for this endpoint; an unrecognised name rejects the whole request. One call costs one credit however many keys you ask for, so request everything you need at once rather than making several calls. |
Available keys (31)
Ask for exactly the calculations you want by listing them in keys. An unknown key rejects the whole request, and you are charged 1 credit however many you ask for — so batch them.
| Key | Extra fields needed | Description |
|---|---|---|
| get_altitude | date_time, latitude, longitude, altitude | How high the body stands above the horizon, in degrees to six decimals; negative means below the horizon. Needs `latitude`, `longitude` and `altitude` in metres. |
| get_apsis | date_time | The next aphelion and perihelion, the body's farthest and nearest points from the Sun. Returns an object `{Aphelion, Perihelion}` with a UTC datetime for each, found by searching forward from the given moment. Available only for the bodies the model covers. |
| get_azimuth | date_time, latitude, longitude, altitude | Where to look for the body along the horizon, in degrees clockwise from north, as a single number to six decimals. Needs `latitude`, `longitude` and `altitude`, and allows for refraction unless a no-refraction switch was set first. |
| get_declination | date_time | Declination, the body's angular distance north or south of the celestial equator, as an object of `degrees`, `minutes` and `seconds`. |
| get_distance | date_time | Distance from the observer in astronomical units, rounded to three decimals. A single number; for the Moon this is a small fraction of an AU. |
| get_ecliptic_speeds | date_time | How fast the body is moving, as an object with `longitude_speed` and `latitude_speed` in degrees per day and `distance_speed` in AU per day, each to six decimals. A negative longitude speed means retrograde. |
| get_equatorial_speeds | date_time | Motion in equatorial coordinates: an object with `right_ascension_speed` and `declination_speed` in degrees per day and `distance_speed` in AU per day, each to six decimals. |
| get_illumination | date_time | The body's apparent visual magnitude at that moment, as a single number to six decimals — smaller and more negative is brighter. Available only for the bodies the illumination model covers; others raise an error. |
| get_latitude | date_time | Ecliptic latitude in degrees to three decimals: how far the body sits above or below the ecliptic plane. A single number, negative for south. |
| get_longitude | date_time | Ecliptic longitude in degrees, 0 to 360, rounded to three decimals — a single number. Whether it is tropical or sidereal depends on the position mode in force. |
| get_right_ascension | date_time | Right ascension, the equatorial counterpart of longitude, as an object of `hours`, `minutes` and `seconds` rather than as decimal degrees. |
| is_retrograde | date_time | True when the body's longitude speed is negative, that is, when it appears to move backwards through the zodiac. A single boolean. |
| is_stationary | date_time | A coarse stationary check: true when the fractional part of the body's daily longitude speed rounds to zero at three decimals. Returns a boolean, and because of that test it is an indicator rather than an exact station. |
| rise_time | date_time, geopos | The body's rise, searched from midnight of the given date. Returns a two-element list: the rise moment as a datetime in the local time implied by `time_zone`, then the raw Swiss Ephemeris Julian day figures. Which definition of 'rise' applies depends on whichever rising or disc switch preceded it in the key array. If the body does not rise or set within the search window - the moon at high latitude, or the sun inside a polar day - the underlying search fails and this returns "2000-11-24T12:00:00Z", which is julian day zero rather than a real instant. Treat that exact value as no result. /api/astro/sunrise/ and /api/astro/moonrise/ return null for the same case. |
| set_astrometric_j_positions | — | Switches to astrometric positions referred to the mean equinox of J2000, with nutation, aberration and light deflection all off. Returns null. |
| set_astrometric_positions | — | Switches to astrometric positions: light-time is corrected for, but annual aberration and gravitational light deflection are not. Returns null. |
| set_barycentric_positions | — | Switches to barycentric positions, referred to the solar system barycentre. Returns null, and works only for physical bodies — not for the nodes or apogees. |
| set_default_positions | — | Switches the object to apparent geocentric positions and installs the ecliptic and equatorial calculation flags that every other positional key relies on. Returns null. Because keys are executed in the order you list them, put this first in `keys`; the position keys fail without it. |
| set_default_rising | — | Restores the Swiss Ephemeris default definition of rise and set for `rise_time` and `set_time`. A switch, not a value — it returns null, and only affects keys listed after it. |
| set_disc_bottom_no_refraction | — | Times rise and set from the bottom edge of the disc with refraction switched off. Returns null. |
| set_disc_bottom_refraction | — | Times rise and set from the bottom edge of the disc, with atmospheric refraction applied. Returns null. |
| set_disc_center_no_refraction | — | Times rise and set from the centre of the disc with refraction switched off — geometric rather than observed. Returns null, and makes any later `get_azimuth` and `get_altitude` airless. |
| set_disc_center_refraction | — | Times rise and set from the centre of the disc, with atmospheric refraction applied. Returns null, and also makes any later `get_azimuth` and `get_altitude` use refracted positions. |
| set_heliocentric_positions | — | Switches to heliocentric positions, referred to the centre of the Sun. Returns null. The Sun, the lunar nodes and the lunar apogees come back as zero in this mode. |
| set_hindu_rising | — | Switches rise and set times to the Hindu convention. Returns null; affects `rise_time` and `set_time` keys listed after it in the array. |
| set_jpl_horizons_positions | — | Switches to apparent positions computed the way JPL Horizons does, for cross-checking against that service. Returns null. |
| set_mean_equinox_positions | — | Switches to positions referred to the mean equinox of date, by turning nutation off. Returns null. |
| set_sidereal_positions | — | Switches to sidereal positions, that is, tropical longitude minus the ayanamsa. Returns null. The ayanamsa itself is set elsewhere, so the prevailing sidereal mode applies. |
| set_time | date_time, geopos | The body's setting, searched from midnight of the given date. Same shape as `rise_time`: [local datetime, raw Julian day figures]. Despite the `set_` prefix this returns a value; it is not one of the switches. If the body does not rise or set within the search window - the moon at high latitude, or the sun inside a polar day - the underlying search fails and this returns "2000-11-24T12:00:00Z", which is julian day zero rather than a real instant. Treat that exact value as no result. /api/astro/sunrise/ and /api/astro/moonrise/ return null for the same case. |
| set_topocentric_positions | latitude, longitude, altitude | Switches to topocentric positions, referred to the observer's own place rather than the centre of the Earth. Requires `latitude`, `longitude` and `altitude` in metres; returns null. The difference is only appreciable for the Moon. |
| set_true_positions | — | Switches to true geometric positions, disregarding light-time — where the body actually is rather than where it appears. Returns null. |
Example request
curl -X POST https://yogataraapi.prahlad.app/api/astro/western/natal-chart/ \
-H "X-API-Key: $OCCULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"date_time":"1990-08-15T10:30:00+05:30","timezone_as_float":5.5,"latitude":26.9124,"longitude":75.7873}'Response
{
"_truncated": true,
"_note": "Response shortened for the catalogue.",
"preview": "{\"data\": {\"zodiac\": \"tropical\", \"planets\": [{\"name\": \"sun\", \"longitude\": 142.125, \"sign\": \"Leo\", \"sign_index\": 5, \"degree_in_sign\": 22.125, \"formatted\": \"22°07' Leo\", \"speed\": 0.960934, \"retrograde\": false}, {\"name\": \"moon\", \"longitude\": 72.66, \"sign\": \"Gemini\", \"sign_index\": 3, \"degree_in_sign\": 12.66, \"formatted\": \"12°39' Gemini\", \"speed\": 14.262958, \"retrograde\": false}, {\"name\": \"mercury\", \"longitude\": 169.176, \"sign\": \"Virgo\", \"sign_index\": 6, \"degree_in_sign\": 19.176, \"formatted\": \"19°10' Virgo\", \"speed\": 0.776615, \"retrograde\": false}, {\"name\": \"venus\", \"longitude\": 121.573, \"sign\": \"Leo\", \"sign_index\": 5, \"degree_in_sign\": 1.573, \"formatted\": \"1°34' Leo\", \"speed\": 1.22118, \"retrograde\": false}, {\"name\": \"mars\", \"longitude\": 51.217, \"sign\": \"Taurus\", \"sign_index\": 2, \"degree_in_sign\": 21.217, \"formatted\": \"21°13' Taurus\", \"speed\": 0.576982, \"retrograde\": false}, {\"name\": \"jupiter\", \"longitude\": 119.337, \"sign\": \"Cancer\", \"sign_index\": 4, \"degree_in_sign\": 29.337, \"formatted\": \"29°20' Cancer\", \"speed\": 0.214649, \"retrograde\": false}, {\"name\": \"saturn\", \"longitude\": 289.878, \"sign\": \"Capricorn\", \"sign_index\": 10, \"degree_in_sign\": 19.878, \"formatted\": \"19°52' Capricorn\", \"speed\": -0.056381, \"retrograde\": true}, {\"name\": \"uranus\", \"longitude\": 275.978, \"sign\": \"Capricorn\", \"sign_index\": 10, \"degree_in_sign\": 5.978, \"formatted\": \"5°58' Capricorn\", \"speed\": -0.023775, \"retrograde\": true}, {\"name\": \"neptune\", \"longitude\": 282.199, \"sign\": \"Capricorn\", \"sign_index\": 10, \"degree_in_sign\": 12.199, \"formatted\": \"12°11' Capricorn\", \"speed\": -0.019063, \"retrograde\": true}, {\"name\": \"pluto\", \"longitude\": 225.084, \"sign\": \"Scorpio\", \"sign_index\": 8, \"degree_in_sign\": 15.084, \"formatted\": \"15°05' Scorpio\", \"speed\": 0.011469, \"retrograde\": false}, {\"name\": \"north_node\", \"longitude\": 307.233, \"sign\": \"Aquarius\", \"sign_index\": 11, \"degree_in_sign\": 7.233, \"formatted\": \"7°13' Aquarius\", \"speed\": 0.014476, \"retrograde\": false}, {\"name\": \"chiron\", \"longitude\": 112.438, \"sign\": \"Cancer\", \"sign_index\": 4, \"degree_in_sign\": 22.438, \"formatted\": \"22°26' Cancer\", \"speed\": 0.099053, \"retrograde\": false}], \"aspects\": [{\"from\": \"sun\", \"to\": \"mars\", \"aspect\": \"square\", \"exact_angle\": 90.0, \"orb\": 0.908, \"allowed_orb\": 8.0, \"applying\": false, \"separation\": 90.908}, {\"from\": \"sun\", \"to\": \"saturn\", \"aspect\": \"quincunx\", \"exact_angle\": 150.0, \"orb\": 2.247, \"allowed_orb\": 3.0, \"applying\": false, \"separation\": 147.753}, {\"from\": \"sun\", \"to\": \"pluto\", \"aspect\": \"square\", \"exact_angle\": 90.0, \"orb\": 7.041, \"allowed_orb\": 8.0, \"applying\": false, \"separation\": 82.959}, {\"from\": \"sun\", \"to\": \"chiron\", \"aspect\": \"semisextile\", \"exact_angle\": 30.0, \"orb\": 0.313, \"allowed_orb\": 2.0, \"applying\": true, \"separation\": 29.687}, {\"from\": \"moon\", \"to\": \"mercury\", \"aspect\": \"square\", \"exact_angle\": 90.0, \"orb\": 6.516, \"allowed_orb\": 8.0, \"applying\": true, \"separation\": 96.516}, {\"from\": \"moon\", \"to\": \"neptune\", \"aspect\": \"quincunx\", \"exact_angle\": 150.0, \"orb\": 0.461, \"allowed_orb\": 3.0, \"applying\": false, \"separation\": 150.461}, {\"from\": \"moon\", \"to\": \"pluto\", \"aspect\": \"quincunx\", \"exact_angle\": 150.0, \"orb\": 2.424, \"allowed_orb\": 3.0, \"applying\": true, \"separation\": 152.424}, {\"from\": \"moon\", \"to\": \"north_node\", \"aspect\": \"trine\", \"exact_angle\": 120.0, \"orb\": 5.427, \"allowed_orb\": 8.0, \"applying\": false, \"separation\": 125.427}, {\"from\": \"mercury\", \"to\": \"mars\", \"aspect\": \"trine\", \"exact_angle\": 120.0, \"orb\": 2.041, \"allowed_orb\": 8.0, \"applying\": true, \"separation\": 117.959}, {\"from\": \"mercury\", \"to\": \"saturn\", \"aspect\": \"trine\", \"exact_angle\": 120.0, \"orb\": 0.702, \"allowed_orb\": 8.0, \"applying\": true, \"separation\": 120.702}, {\"from\": \"mercury\", \"to\": \"neptune\", \"aspect\": \"trine\", \"exact_angle\": 120.0, \"orb\": 6.977, \"allowed_orb\": 8.0, \"applying\": false, \"separation\": 113.023}, {\"from\": \"mercury\", \"to\": \"pluto\", \"aspect\": \"sextile\", \"exact_angle\": 60.0, \"orb\": 4.092, \"allowed_orb\": 6.0, \"applying\": false, \"separation\": 55.908}, {\"from\": \"mercury\", \"to\": \"chiron\", \"asp"
}Captured from a real call using the exact request above. Results sit under data, keyed by what you requested.
Errors
Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.