POST/api/astro/mundane/1 credit

Mundane astrology

Mundane astrology reads the year for a country rather than for a person. Its central device is the samvatsara cabinet: ten 'officers' of the year, each a planet, each fixed by the weekday on which a particular solar event falls — the king from the lunar new year, the minister from the Sun's entry into Aries, the lord of clouds from its entry into Ardra, and so on down to the lords of grain, treasury and fruits. A year with Saturn as king is read very differently from one with Jupiter. Pass the year you want plus a place and UTC offset. das_adhikari returns the whole cabinet in one object and is the key to start with; the individual keys — king_of_year, mantri_of_year, meghesha_of_year and the rest — return the same planets one at a time. vaahan_of_samvat gives the year's symbolic vehicle, derived from the king. Alongside the cabinet the endpoint returns the year's astronomical frame — equinoxes, solstices, indian_ritus for the six seasons as real date ranges, chaitra_shukla_pratipada and ardra_entry — and four charts cast for particular ingresses: jagat_lagna_chart at the Sun's entry into Aries, ardra_pravesh_chart for the monsoon, and sharatsasya_chart and greeshmasasya_chart for the winter and summer crops. sapta_nadi_chakra and samvatsara_purusha_chakra are static reference tables that do not vary by year, and nakshatra_lord_effects looks a single nakshatra up in the first of them. That key's nakshatra field uses an older transliteration and covers only twenty-six names — check the field's list rather than assuming modern spellings.

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

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
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.
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.
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 -90 · max 90
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
nakshatra	string	required	`KrittikaVisaakhaAnooraadhaBharaniRohiniSwaatiJyeshthaAshwiniMrigasiraChitraMoolaRevati` Used only by the 'nakshatra_lord_effects' key. EXACT case-sensitive match against the Sapta Nadi Chakra table - these are older transliterations, not the modern spellings; note 'Aardra' (not Ardra), 'Aasresha' (not Ashlesha), 'Makha' (not Magha), 'Sravanam' (not Shravana), 'Visaakha', 'Anooraadha', 'Mrigasira', 'Pushyami', 'Satabhishak', 'Poorvaabhaadra', 'Uttaraashaadha'. Only 26 of the 28 nakshatra names appear - 'Poorvaashaadha' and 'Uttaraabhaadra' are absent from the table. An unmatched name does NOT error: the method returns null.
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
year	integer	required	Year of birth as a number, e.g. 1990. Four digits.

Available keys (24)

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
ardra_entry	—	The exact moment the Sun reaches 66°40', the start of Ardra nakshatra — the traditional marker for the monsoon reckoning. A single timestamp.
ardra_pravesh_chart	—	The same chart structure cast for the moment the Sun enters Ardra nakshatra, the chart read for the monsoon. Returns {entry_time, chart, house_planets}.
chaitra_shukla_pratipada	—	The Hindu lunar new year: the sunrise of the day carrying the first tithi of Chaitra's bright fortnight, found by scanning March and April of the requested year for a new moon with the Sun in Pisces. A single timestamp, or null if the scan finds no match.
das_adhikari	—	The year's whole cabinet in one object, keyed King, Minister, Lord of Clouds, Lord of Summer Crops, Lord of Defence, Lord of Treasury, Lord of Juicy Products, Lord of Food Grains, Lord of Metals, Lord of Fruits and Vehicle of Year. The first ten values are planet names and the last is the vehicle. Start here rather than requesting the ten individual keys.
dhaanyesha_of_year	—	Dhanyesha, lord of grains: the planet ruling the weekday of the Sun's entry into Sagittarius. A single English planet name.
dhanesha_of_year	—	Dhanesha, lord of the treasury: the planet ruling the weekday of the Sun's entry into Virgo. A single English planet name.
durgesha_of_year	—	Durgesha, lord of forts and defence: the planet ruling the weekday of the Sun's entry into Leo. A single English planet name.
equinoxes	—	The year's two equinox instants, found as the Sun's tropical crossings of 0 and 180 degrees. A two-element list, vernal first then autumnal.
greeshmasasya_chart	—	The summer-crop chart, cast for the Sun's entry into Pisces. Returns {entry_time, chart, house_planets}.
indian_ritus	—	The six Indian seasons as real date ranges, each a sixty-degree arc of tropical solar longitude positioned so that each equinox and solstice falls at the middle or the edge of a season. Returns a list of six objects — {ritu, name, subtitle, begins, ends, tropical_zodiac, note, image_url} — in the order Vasant, Grishma, Varsha, Sharad, Hemant, Shishir.
jagat_lagna_chart	—	The world chart, cast for the exact moment of the Sun's entry into Aries. Returns {ingress_time, chart, house_planets}: chart is a full rashi chart in sign-and-degree notation with celestial, houses and ascendant sections, and house_planets maps each house to the planets occupying it.
king_of_year	—	The Raja of the year — the planet ruling the weekday on which Chaitra Shukla Pratipada falls. A single English planet name. In mundane practice this planet's nature sets the tone read into the whole year.
mantri_of_year	—	The Mantri, or minister of the year: the planet ruling the weekday of the Sun's entry into Aries. A single English planet name.
meghesha_of_year	—	Meghesha, lord of the clouds: the planet ruling the weekday of the Sun's entry into Ardra. A single English planet name, read for the year's rainfall.
nakshatra_lord_effects	nakshatra	Looks the nakshatra you pass in up in the Sapta Nadi Chakra and returns {lord, nadi, means, effect}: the ruling planet, the nadi's name, what that nadi signifies and the weather it is read for. Returns null for any name absent from the table, which uses older transliterations, covers twenty-six names and omits Poorvaashaadha and Uttaraabhaadra.
neersesha_of_year	—	The planet ruling the weekday of the Sun's entry into Capricorn. A single English planet name. Classically this office is the lord of waters; this API labels it Lord of Metals in das_adhikari, and the description follows the code rather than the classical usage.
phalesha_of_year	—	Phalesha, lord of fruits: the planet ruling the weekday of the Sun's entry into Pisces. A single English planet name.
rasesha_of_year	—	Rasesha, lord of juices and liquid produce: the planet ruling the weekday of the Sun's entry into Libra. A single English planet name.
samvatsara_purusha_chakra	—	The body-part associations of the year-person. Returns a static object keyed by body part — 'Entire body', 'Navel', 'Heart' and 'Vitality' — each with a nakshatras list, and a significance note on the last. This is a partial table covering six nakshatras, not all twenty-seven.
sapta_nadi_chakra	—	The full seven-nadi weather table that nakshatra_lord_effects looks into: an object keyed by the seven planets, each {nakshatras, nadi, means, effect}. Static reference data, identical for every request. Note that a few nakshatras appear under more than one planet, and a lookup returns the first match.
sashyesha_of_year	—	Sasyesha, lord of crops: the planet ruling the weekday of the Sun's entry into Cancer. A single English planet name; das_adhikari lists it as Lord of Summer Crops.
sharatsasya_chart	—	The winter-crop chart, cast for the Sun's entry into Virgo. Returns {entry_time, chart, house_planets}, the same structure as the other mundane charts.
solstices	—	The year's two solstice instants. A two-element list — note the order is winter first (Sun at 270 degrees, in December of the requested year) and summer second (Sun at 90 degrees, in June), not chronological.
vaahan_of_samvat	—	The year's symbolic vehicle, looked up from the king of the year — Horse for Sun, Elephant for Moon, Ox/boat for Mars, Swing for Mercury, Boat for Jupiter, Elephant/Frog for Venus, Horse/Buffalo for Saturn. A single string.

Example request

curl -X POST https://yogataraapi.prahlad.app/api/astro/mundane/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys":["nakshatra_lord_effects"],"year":2025,"date_time":"2025-02-13T05:00:37.682Z","nakshatra":"Krittika","latitude":26.9124,"longitude":75.7873,"timezone_as_float":5.5}'

Response

{
  "data": {
    "nakshatra_lord_effects": {
      "lord": "Saturn",
      "nadi": "Chandaa",
      "means": "Aggressive",
      "effect": "Heat, Wind"
    }
  },
  "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.