Skip to content
Occult API
POST/api/planetary_details/1 credit

Planetary details

A single call that runs nine separate ephemeris scans over a date range and returns them together. It is the endpoint to reach for when you want everything that happens to the planets between two dates rather than a snapshot: sign and nakshatra changes, retrograde spells, declination alignments and out-of-bounds excursions. `start_date` and `end_date` bound the window, `planet_name` and `sign` narrow the three planet-specific sections, and `longitude` is the ecliptic degree tested by the position search. Supplying `geo_latitude` and `geo_longitude` adds an extra section for ascendant ingress and is otherwise omitted. Note that the window is scanned in full, so a multi-year range is considerably slower than a few days. The response holds, under keys with spaces in their names, `sign transitions`, `planet at position` (when the named planet sits at the given longitude in the given sign), `planet ingress exit` (entry and exit times for the named planet in the named sign only), `planet nakshatra ingress exit` (keyed by all twenty-seven nakshatras, each a list of `{start_date, end_date}` windows), `planet sankranti times` (keyed by every supported body, including the Uranian points and planetary moons), `planet retrogression dates` (keyed by planet, each a list of `{start, end}`), `planet krantisamya dates` (a list of `{Planet_1, Planet_2, DateTime, Alignment}` where Alignment is North-North, South-South or Opposite, that is, equal or mirrored declination), `abhijit nakshatra periods` and `planet oob range` (the spells when the body is beyond the Sun's maximum declination). Empty lists mean nothing of that kind happened inside your window.

https://yogataraapi.prahlad.app/api/planetary_details/
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

FieldTypeRequiredNotes
end_datestring (date-time)required
longitudenumber (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

planet_namestringrequired
sunmoonmercuryvenusmarsjupitersaturnuranusneptuneplutotruenodemeannode

One of: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, truenode, meannode. Lowercase. Other swisseph body names are accepted by validation but have no data and will fail.

signstringrequired
AriesTaurusGeminiCancerLeoVirgoLibraScorpioSagittariusCapricornAquariusPisces

CASE-SENSITIVE - Title-case English sign names exactly as spelled; 'aries' fails. Also used at to filter the ingress/exit result down to the requested sign.

start_datestring (date-time)required
geo_latitudenumber (double)optional

Observer geographic latitude (-90 to 90). Required for ascendant entry data.

min -90 · max 90

geo_longitudenumber (double)optional

Observer geographic longitude (-180 to 180). Required for ascendant entry data.

min -180 · max 180

Example request

curl -X POST https://yogataraapi.prahlad.app/api/planetary_details/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2024-11-21T08:33:35.539Z","end_date":"2024-11-22T08:33:35.539Z","longitude":76.125,"planet_name":"mercury","sign":"Taurus"}'

Response

{
  "_truncated": true,
  "_note": "Response shortened for the catalogue.",
  "preview": "{\"data\": {\"sign transitions\": {}, \"planet at position\": {\"mercury\": {\"positions\": []}}, \"planet ingress exit\": {\"mercury\": {}}, \"planet nakshatra ingress exit\": {\"mercury\": {\"Ashwini\": [], \"Bharani\": [], \"Krittika\": [], \"Rohini\": [], \"Mrigasira\": [], \"Aardra\": [], \"Punarvasu\": [], \"Pushyami\": [], \"Aasresha\": [], \"Makha\": [], \"Poorva Phalguni\": [], \"Uttara Phalguni\": [], \"Hasta\": [], \"Chitra\": [], \"Swaati\": [], \"Visaakha\": [], \"Anooraadha\": [], \"Jyeshtha\": [{\"start_date\": \"2024-11-21 08:33:35\", \"end_date\": \"2024-11-22 08:33:35\"}], \"Moola\": [], \"Poorvaashaadha\": [], \"Uttaraashaadha\": [], \"Sravanam\": [], \"Dhanishtha\": [], \"Satabhishak\": [], \"Poorvaabhaadra\": [], \"Uttaraabhaadra\": [], \"Revati\": []}}, \"planet sankranti times\": {\"sun\": [], \"moon\": [], \"mercury\": [], \"venus\": [], \"mars\": [], \"jupiter\": [], \"saturn\": [], \"uranus\": [], \"neptune\": [], \"pluto\": [], \"truenode\": [], \"meannode\": [], \"chiron\": [], \"pholus\": [], \"ceres\": [], \"pallas\": [], \"juno\": [], \"vesta\": [], \"cupido\": [], \"hades\": [], \"zeus\": [], \"kronos\": [], \"apollon\": [], \"admetos\": [], \"vulkanus\": [], \"poseidon\": [], \"selena\": [], \"phobos\": [], \"deimos\": [], \"io\": [], \"europa\": [], \"ganymede\": [], \"callisto\": [], \"titan\": [], \"triton\": [], \"charon\": []}, \"planet retrogression dates\": {\"jupiter\": [{\"start\": \"2024-11-21 08:33:35\", \"end\": \"2024-11-22 08:33:35\"}], \"mars\": [], \"meannode\": [{\"start\": \"2024-11-21 08:33:35\", \"end\": \"2024-11-22 08:33:35\"}], \"mercury\": [], \"moon\": [], \"neptune\": [{\"start\": \"2024-11-21 08:33:35\", \"end\": \"2024-11-22 08:33:35\"}], \"pluto\": [], \"saturn\": [], \"sun\": [], \"truenode\": [{\"start\": \"2024-11-21 08:33:35\", \"end\": \"2024-11-22 08:33:35\"}], \"uranus\": [{\"start\": \"2024-11-21 08:33:35\", \"end\": \"2024-11-22 08:33:35\"}], \"venus\": []}, \"planet krantisamya dates\": [{\"Planet_1\": \"sun\", \"Planet_2\": \"truenode\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"meannode\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"zeus\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"Opposite\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"kronos\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"apollon\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"Opposite\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"admetos\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"vulkanus\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"poseidon\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"Opposite\"}, {\"Planet_1\": \"sun\", \"Planet_2\": \"selena\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"mercury\", \"Planet_2\": \"venus\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"mars\", \"Planet_2\": \"phobos\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"mars\", \"Planet_2\": \"deimos\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"jupiter\", \"Planet_2\": \"io\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"jupiter\", \"Planet_2\": \"europa\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"jupiter\", \"Planet_2\": \"ganymede\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"jupiter\", \"Planet_2\": \"callisto\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"saturn\", \"Planet_2\": \"titan\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"neptune\", \"Planet_2\": \"triton\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"pluto\", \"Planet_2\": \"charon\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"South-South\"}, {\"Planet_1\": \"truenode\", \"Planet_2\": \"meannode\", \"DateTime\": \"2024-11-21 08:33:35\", \"Alignment\": \"North-North\"}, {\"Planet_1\": \"truenode\", \"Planet_2\": \"zeus\", \"DateTime\": \"2024-11-21 08:33"
}

Captured from a real call using the exact request above. Results sit under data.

Errors

Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.