POST/api/astro/celestial/1 क्रेडिट

खगोलीय स्थितियाँ

एक या ज़्यादा पिंडों का कच्चा एफ़ेमेरिस: ग्रह कहाँ है, कितनी तेज़ी से चल रहा है, कब उदय और अस्त होता है, वक्री है या नहीं। यह बाकी API के नीचे की खगोलीय परत है, जो यहाँ सीधे उपलब्ध है, और यह नौ वैदिक ग्रहों से कहीं आगे तक जाती है — बाहरी ग्रह, काइरॉन और क्षुद्रग्रह, यूरेनियन काल्पनिक बिंदु और कई ग्रहों के चंद्रमा, सब माँगे जा सकते हैं। keys दो तरह की हैं। `set_*` keys स्विच हैं: ये तय करती हैं कि स्थितियों या उदय-अस्त के समय की गणना कैसे हो — भूकेंद्रीय, स्थलकेंद्रीय या सूर्यकेंद्रीय, दृश्य या वास्तविक, न्यूटेशन के साथ या बिना, निरयन या सायन, हिंदू उदय या बिंब-केंद्र उदय — और हर एक null लौटाती है। `get_*` keys, और साथ में `rise_time`, `set_time`, `is_retrograde` और `is_stationary`, वैल्यू लौटाती हैं। keys उसी क्रम में चलती हैं जिसमें आप उन्हें लिखते हैं, इसलिए कोई स्विच ऐरे में केवल अपने बाद वाली वैल्यू keys पर असर डालता है। `planet_names` में बड़े अक्षरों वाले नामों की सूची दी जाती है, और उत्तर की keys यही नाम होते हैं, इसलिए MARS के लिए की गई कॉल का उत्तर `{"data": {"MARS": {"get_longitude": 123.45}}}` होता है। अनजान नाम से अनुरोध विफल नहीं होता: उस नाम की प्रविष्टि `{"error": "Unknown planet '<name>'"}` के रूप में आती है। ध्यान दें कि यहाँ पातों के नाम MEAN_NODE और TRUE_NODE हैं, /api/astro/chart/ वाली 'northtruenode' वर्तनी नहीं।

https://api.occultapi.com/api/astro/celestial/

अनुरोध आज़माएँ

ऑथेंटिकेशन

अपनी कुंजी X-API-Key हेडर में भेजें। कुंजी सिर्फ़ सर्वर पर रखने की चीज़ है — इसे कभी ब्राउज़र के JavaScript या मोबाइल ऐप में न डालें।

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

अनुरोध के फ़ील्ड

फ़ील्ड	टाइप	ज़रूरी	टिप्पणी
altitude	number (double)	ज़रूरी
date_time	string (date-time)	ज़रूरी	जिस क्षण की गणना करनी है, ISO 8601 फ़ॉर्मैट में। ऑफ़सेट या अंत में Z हमेशा लगाएँ - बिना ज़ोन वाली वैल्यू UTC नहीं, बल्कि Asia/Kolkata (UTC+05:30) मानी जाती है, और तब 200 के साथ पिछले दिन का नतीजा मिल सकता है। '2026-09-01T06:00:00Z' और '2026-09-01 06:00:00' दो अलग क्षण हैं, और इनके उत्तर भी अलग आते हैं। यह फ़ॉर्मैट की शर्त है, enum नहीं। DRF DateTimeField: केवल ISO-8601 (DRF के डिफ़ॉल्ट इनपुट फ़ॉर्मैट), जैसे "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" या "2026-09-01 06:00:00" (समय क्षेत्र न हो, तो UTC माना जाता है)।
keys	array	ज़रूरी	कौन-सी गणनाएँ लौटानी हैं, उनके नामों की सूची। इस एंडपॉइंट की key तालिका देखें; एक भी अनजान नाम हो, तो पूरा अनुरोध अस्वीकार हो जाता है। आप जितनी चाहें keys माँगें, एक कॉल पर एक ही क्रेडिट लगता है, इसलिए कई कॉल करने के बजाय जो कुछ चाहिए, सब एक साथ माँग लें। `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` स्ट्रिंग का ऐरे। `set_` keys Celestial ऑब्जेक्ट पर गणना के फ़्लैग बदलती हैं; `get_` / `rise_time` / `set_time` / `is_*` keys वैल्यू लौटाती हैं।
planet_names	array	ज़रूरी	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` स्ट्रिंग का ऐरे, कम से कम 1 आइटम। ध्यान दें कि यहाँ पातों के नाम 'MEAN_NODE'/'TRUE_NODE' हैं, कुंडली के उत्तर वाली 'northtruenode' शैली नहीं। अनजान नाम से अनुरोध विफल नहीं होता: उस नाम की प्रविष्टि {"error": "Unknown planet '<X>'"} के रूप में आती है।
time_zone	number (double)	ज़रूरी	min -12 · max 14
latitude	number (double)	वैकल्पिक	स्थान का अक्षांश, दशमलव अंशों में। उत्तरी अक्षांश धनात्मक होता है, दक्षिणी ऋणात्मक। उदाहरण: जयपुर के लिए 26.9124, न्यूयॉर्क के लिए 40.7128। कला और विकला स्वीकार नहीं की जातीं - पहले दशमलव अंशों में बदल लें। min -89.9 · max 89.9
longitude	number (double)	वैकल्पिक	स्थान का देशांतर, दशमलव अंशों में। पूर्वी देशांतर धनात्मक होता है, पश्चिमी ऋणात्मक। उदाहरण: जयपुर के लिए 75.7873, न्यूयॉर्क के लिए -74.0060। चिह्न पर ध्यान दें: माइनस छूट गया, तो न्यूयॉर्क चीन में पहुँच जाएगा। min -180 · max 180

उपलब्ध keys (31)

आपको जो गणनाएँ चाहिए, बस उन्हीं के नाम keys में लिखें। कोई एक भी अनजान नाम हुआ तो पूरा अनुरोध लौटा दिया जाता है। आप कितनी भी गणनाएँ माँगें, शुल्क 1 क्रेडिट ही लगता है — इसलिए सब एक साथ माँगें।

Key	और कौन-से फ़ील्ड चाहिए	विवरण
get_altitude	date_time, latitude, longitude, altitude	पिंड क्षितिज से कितना ऊपर है, अंशों में, छह दशमलव स्थानों तक; ऋणात्मक का मतलब है क्षितिज के नीचे। `latitude`, `longitude` और मीटर में `altitude` चाहिए।
get_apsis	date_time	अगला अपसौर और उपसौर, यानी सूर्य से पिंड का सबसे दूर और सबसे पास वाला बिंदु। ऑब्जेक्ट `{Aphelion, Perihelion}` लौटाती है, जिसमें दोनों का UTC datetime होता है; ये दिए गए क्षण से आगे खोजकर निकाले जाते हैं। केवल उन पिंडों के लिए उपलब्ध, जो मॉडल में शामिल हैं।
get_azimuth	date_time, latitude, longitude, altitude	क्षितिज पर पिंड किस दिशा में दिखेगा, उत्तर से घड़ी की दिशा में अंशों में, छह दशमलव स्थानों तक एक संख्या। `latitude`, `longitude` और `altitude` चाहिए। अपवर्तन को हिसाब में लिया जाता है, जब तक पहले कोई बिना-अपवर्तन वाला स्विच सेट न किया गया हो।
get_declination	date_time	क्रांति, यानी खगोलीय विषुवत् से पिंड की उत्तर या दक्षिण कोणीय दूरी, `degrees`, `minutes` और `seconds` वाले ऑब्जेक्ट के रूप में।
get_distance	date_time	प्रेक्षक से दूरी, खगोलीय इकाइयों में, तीन दशमलव स्थानों तक पूर्णांकित। एक संख्या; चंद्रमा के लिए यह AU का बहुत छोटा-सा अंश होती है।
get_ecliptic_speeds	date_time	पिंड कितनी तेज़ी से चल रहा है: एक ऑब्जेक्ट, जिसमें `longitude_speed` और `latitude_speed` अंश प्रति दिन में और `distance_speed` AU प्रति दिन में है, सब छह दशमलव स्थानों तक। ऋणात्मक भोगांश गति का मतलब है कि ग्रह वक्री है।
get_equatorial_speeds	date_time	विषुवतीय निर्देशांकों में गति: एक ऑब्जेक्ट, जिसमें `right_ascension_speed` और `declination_speed` अंश प्रति दिन में और `distance_speed` AU प्रति दिन में है, सब छह दशमलव स्थानों तक।
get_illumination	date_time	उस क्षण पिंड का दृश्य मैग्निट्यूड, छह दशमलव स्थानों तक एक संख्या — संख्या जितनी छोटी और जितनी ज़्यादा ऋणात्मक, पिंड उतना चमकीला। केवल उन पिंडों के लिए उपलब्ध, जो प्रकाश मॉडल में शामिल हैं; बाकी पर त्रुटि आती है।
get_latitude	date_time	क्रांतिवृत्तीय अक्षांश (शर), अंशों में, तीन दशमलव स्थानों तक: पिंड क्रांतिवृत्त के तल से कितना ऊपर या नीचे है। एक संख्या; दक्षिण के लिए ऋणात्मक।
get_longitude	date_time	क्रांतिवृत्तीय भोगांश, अंशों में, 0 से 360 के बीच, तीन दशमलव स्थानों तक पूर्णांकित — एक संख्या। यह सायन होगा या निरयन, यह उस समय लागू स्थिति मोड पर निर्भर है।
get_right_ascension	date_time	विषुवांश, यानी भोगांश का विषुवतीय रूप, दशमलव अंशों में नहीं, बल्कि `hours`, `minutes` और `seconds` वाले ऑब्जेक्ट के रूप में।
is_retrograde	date_time	true, जब पिंड की भोगांश गति ऋणात्मक हो, यानी जब वह राशिचक्र में पीछे की ओर चलता दिखे। एक बूलियन।
is_stationary	date_time	स्थिर होने की मोटी जाँच: true, जब पिंड की दैनिक भोगांश गति का दशमलव भाग तीन दशमलव स्थानों तक पूर्णांकित करने पर शून्य हो जाए। एक बूलियन लौटाती है, और इसी जाँच की वजह से यह सटीक स्तंभन नहीं, बस एक संकेत है।
rise_time	date_time, geopos	पिंड का उदय, उस स्थान पर दी गई तारीख़ की स्थानीय आधी रात (`time_zone` ऑफ़सेट के हिसाब से) से खोजा जाता है। दो आइटम वाली सूची लौटाता है: पहले उदय का क्षण, `time_zone` से निकलने वाले स्थानीय समय में datetime के रूप में, फिर जूलियन दिन के कच्चे आँकड़े। 'उदय' की कौन-सी परिभाषा लागू होगी, यह keys ऐरे में इससे पहले आए उदय या बिंब वाले स्विच पर निर्भर करता है। अगर खोज की अवधि में पिंड उदय या अस्त नहीं होता - ऊँचे अक्षांश पर चंद्रमा, या ध्रुवीय दिन के भीतर सूर्य - तो अंदर की खोज विफल हो जाती है और यह "2000-11-24T12:00:00Z" लौटाता है, जो कोई असली क्षण नहीं, जूलियन दिन शून्य है। ठीक इसी मान का मतलब है कि कोई नतीजा नहीं मिला। ऐसी स्थिति में /api/astro/sunrise/ और /api/astro/moonrise/ null लौटाते हैं।
set_astrometric_j_positions	—	J2000 के मध्यम विषुव के सापेक्ष एस्ट्रोमेट्रिक स्थितियाँ चालू करती है, जिनमें न्यूटेशन, विपथन और प्रकाश विचलन, सब बंद रहते हैं। null लौटाती है।
set_astrometric_positions	—	एस्ट्रोमेट्रिक स्थितियाँ चालू करती है: प्रकाश-काल का सुधार होता है, पर वार्षिक विपथन और गुरुत्वीय प्रकाश विचलन का नहीं। null लौटाती है।
set_barycentric_positions	—	बैरीसेंट्रिक स्थितियाँ चालू करती है, यानी सौरमंडल के द्रव्यमान केंद्र के सापेक्ष। null लौटाती है, और केवल भौतिक पिंडों पर काम करती है — पातों या अपभू बिंदुओं पर नहीं।
set_default_positions	—	यह स्विच है, वैल्यू नहीं: गतियों सहित दृश्य भूकेंद्रीय स्थितियाँ सेट करती है, जो इस एंडपॉइंट का सायन (TROPICAL) डिफ़ॉल्ट है। null लौटाती है। `set_*` स्विच केवल उन keys पर लागू होते हैं जो `keys` में उनके बाद लिखी हों, इसलिए क्रम मायने रखता है - इसे सबसे पहले रखें, या डिफ़ॉल्ट वापस लाने के लिए किसी दूसरे स्विच के बाद। ध्यान दें कि /api/astro/star/ पर इसी नाम की key इसके उलट निरयन (SIDEREAL) स्थितियाँ सेट करती है।
set_default_rising	—	`rise_time` और `set_time` के लिए उदय और अस्त की डिफ़ॉल्ट परिभाषा वापस लाती है। यह स्विच है, वैल्यू नहीं — null लौटाती है, और केवल अपने बाद लिखी keys पर असर डालती है।
set_disc_bottom_no_refraction	—	उदय और अस्त का समय बिंब के निचले किनारे से लेती है, अपवर्तन बंद रखकर। null लौटाती है।
set_disc_bottom_refraction	—	उदय और अस्त का समय बिंब के निचले किनारे से लेती है, वायुमंडलीय अपवर्तन जोड़कर। null लौटाती है।
set_disc_center_no_refraction	—	उदय और अस्त का समय बिंब के केंद्र से लेती है, अपवर्तन बंद रखकर — यानी जैसा दिखता है वैसा नहीं, ज्यामितीय। null लौटाती है, और इसके बाद आने वाली `get_azimuth` और `get_altitude` भी बिना वायुमंडल के हिसाब से निकलती हैं।
set_disc_center_refraction	—	उदय और अस्त का समय बिंब के केंद्र से लेती है, वायुमंडलीय अपवर्तन जोड़कर। null लौटाती है, और इसके बाद आने वाली `get_azimuth` और `get_altitude` भी अपवर्तन वाली स्थितियों से निकलती हैं।
set_heliocentric_positions	—	सूर्यकेंद्रीय स्थितियाँ चालू करती है, यानी सूर्य के केंद्र के सापेक्ष। null लौटाती है। इस मोड में सूर्य, चंद्र पात और चंद्र अपभू बिंदु शून्य आते हैं।
set_hindu_rising	—	उदय और अस्त के समय हिंदू परिपाटी से निकालती है। null लौटाती है; ऐरे में इसके बाद लिखी `rise_time` और `set_time` keys पर असर डालती है।
set_jpl_horizons_positions	—	दृश्य स्थितियाँ उसी तरीके से निकालती है जैसे JPL Horizons, ताकि उस सेवा से मिलान किया जा सके। null लौटाती है।
set_mean_equinox_positions	—	न्यूटेशन बंद करके, उसी तारीख़ के मध्यम विषुव के सापेक्ष स्थितियाँ चालू करती है। null लौटाती है।
set_sidereal_positions	—	निरयन स्थितियाँ चालू करती है, यानी सायन भोगांश में से अयनांश घटाकर। null लौटाती है। अयनांश ख़ुद कहीं और सेट होता है, इसलिए उस समय जो निरयन मोड लागू है, वही चलता है।
set_time	date_time, geopos	पिंड का अस्त, उस स्थान पर दी गई तारीख़ की स्थानीय आधी रात (`time_zone` ऑफ़सेट के हिसाब से) से खोजा जाता है। रूप `rise_time` जैसा ही है: [स्थानीय datetime, जूलियन दिन के कच्चे आँकड़े]। `set_` उपसर्ग के बावजूद यह एक मान लौटाता है; यह स्विचों में से नहीं है। अगर खोज की अवधि में पिंड उदय या अस्त नहीं होता - ऊँचे अक्षांश पर चंद्रमा, या ध्रुवीय दिन के भीतर सूर्य - तो अंदर की खोज विफल हो जाती है और यह "2000-11-24T12:00:00Z" लौटाता है, जो कोई असली क्षण नहीं, जूलियन दिन शून्य है। ठीक इसी मान का मतलब है कि कोई नतीजा नहीं मिला। ऐसी स्थिति में /api/astro/sunrise/ और /api/astro/moonrise/ null लौटाते हैं।
set_topocentric_positions	latitude, longitude, altitude	स्थलकेंद्रीय स्थितियाँ चालू करती है, जो पृथ्वी के केंद्र के बजाय प्रेक्षक की अपनी जगह के सापेक्ष होती हैं। `latitude`, `longitude` और मीटर में `altitude` ज़रूरी हैं; null लौटाती है। फ़र्क केवल चंद्रमा के लिए ध्यान देने लायक होता है।
set_true_positions	—	प्रकाश-काल को छोड़कर वास्तविक ज्यामितीय स्थितियाँ चालू करती है — पिंड जहाँ दिखता है वहाँ नहीं, बल्कि जहाँ वह सच में है। null लौटाती है।

उदाहरण अनुरोध

curl -X POST https://api.occultapi.com/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"]}'

उत्तर

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

ऊपर वाले अनुरोध से ही की गई असली कॉल का उत्तर। नतीजे data के अंदर हैं, हर नतीजा उसी नाम से जिससे आपने माँगा।

त्रुटियाँ

कुंजी और क्रेडिट की जाँच से आई त्रुटियाँ { "error": "…", "message": "<code>", "is_error": true } रूप में आती हैं। लोगों को error दिखाएँ और कोड में message देखकर फ़ैसला करें। पूरी सूची त्रुटि संदर्भ में है।