POST/api/astro/celestial/1 credit

Celestial positions

Raw ephemeris for one or more bodies: where a planet is, how fast it is moving, when it rises and sets, whether it is retrograde. This is the astronomy layer beneath the rest of the API, exposed directly, and it reaches well past the nine Vedic grahas — the outer planets, Chiron and the asteroids, the Uranian fictitious points and several planetary moons are all addressable. The keys divide into two kinds. The `set_*` keys are switches: they change how positions or rise and set times are computed — geocentric, topocentric or heliocentric, apparent or true, with or without nutation, sidereal or tropical, Hindu rising or disc-centre rising — and each returns null. The `get_*` keys, along with `rise_time`, `set_time`, `is_retrograde` and `is_stationary`, return values. Because keys are executed in the order you list them, a switch only affects the value keys that come after it in the array. `planet_names` takes a list of upper-case names and the response is keyed by them, so a call for MARS comes back as `{"data": {"MARS": {"get_longitude": 123.45}}}`. An unrecognised name does not fail the request: that entry comes back as `{"error": "Unknown planet '<name>'"}`. Note the nodes are called MEAN_NODE and TRUE_NODE here, not the 'northtruenode' spelling /api/astro/chart/ uses.

https://yogataraapi.prahlad.app/api/astro/celestial/

Test Request

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/json

Request fields

Field	Type	Required	Notes
altitude	number (double)	required
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. FORMAT constraint, not an enum. DRF DateTimeField: ISO-8601 only (DRF default input formats), e.g. "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" or "2026-09-01 06:00:00" (no timezone = UTC assumed).
keys	array	required	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. `set_default_risingset_hindu_risingset_disc_center_refractionset_disc_bottom_refractionset_disc_center_no_refractionset_disc_bottom_no_refractionset_default_positionsset_true_positionsset_topocentric_positionsset_heliocentric_positionsset_barycentric_positionsset_astrometric_positions` Array of strings. The `set_` keys mutate calculation flags on the Celestial object; the `get_` / `rise_time` / `set_time` / `is_*` keys return values.
planet_names	array	required	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` Array of strings, min length 1. Note the nodes are named 'MEAN_NODE'/'TRUE_NODE' here, not the 'northtruenode' style used in chart output. An unrecognised name does not fail the request: that entry comes back as {"error": "Unknown planet '<X>'"}.
time_zone	number (double)	required	min -12 · max 14
latitude	number (double)	optional	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)	optional	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

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	—	A switch, not a value: sets apparent geocentric positions with speeds, which is the TROPICAL default for this endpoint. Returns null. The `set_*` switches apply only to the keys listed after them in `keys`, so order matters - put this first, or after another switch to restore the default. Note that the key of the same name on /api/astro/star/ sets SIDEREAL positions instead.
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/celestial/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2024-11-20T08:40:08.658Z","keys":["set_default_positions","set_hindu_rising"],"latitude":26.9124,"longitude":75.7873,"time_zone":5.5,"altitude":0,"planet_names":["SUN"]}'

Response

{
  "data": {
    "SUN": {
      "set_default_positions": null,
      "set_hindu_rising": null
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

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.