POST/api/astro/celestial/1 Credit

Himmelspositionen

Rohe Ephemeridendaten für einen oder mehrere Himmelskörper: wo ein Planet steht, wie schnell er sich bewegt, wann er auf- und untergeht, ob er rückläufig ist. Das ist die astronomische Grundschicht der gesamten API, hier direkt zugänglich, und sie reicht weit über die neun vedischen Grahas hinaus: Auch die äußeren Planeten, Chiron und die Asteroiden, die fiktiven uranischen Punkte und mehrere Planetenmonde lassen sich abfragen. Es gibt zwei Arten von Keys. Die `set_*`-Keys sind Schalter: Sie legen fest, wie Positionen oder Auf- und Untergangszeiten berechnet werden – geozentrisch, topozentrisch oder heliozentrisch, scheinbar oder wahr, mit oder ohne Nutation, siderisch oder tropisch, hinduistischer Aufgang oder Aufgang der Scheibenmitte – und liefern jeweils null. Die `get_*`-Keys sowie `rise_time`, `set_time`, `is_retrograde` und `is_stationary` liefern Werte. Weil die Keys in der Reihenfolge ausgeführt werden, in der du sie aufführst, wirkt ein Schalter nur auf die Wert-Keys, die im Array nach ihm stehen. `planet_names` nimmt eine Liste von Namen in Großbuchstaben entgegen, und die Antwort verwendet sie als Schlüssel: Ein Aufruf für MARS kommt als `{"data": {"MARS": {"get_longitude": 123.45}}}` zurück. Ein unbekannter Name lässt die Anfrage nicht scheitern; dieser Eintrag lautet dann `{"error": "Unknown planet '<name>'"}`. Beachte: Die Mondknoten heißen hier MEAN_NODE und TRUE_NODE, nicht 'northtruenode' wie bei /api/astro/chart/.

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

Anfrage testen

Authentifizierung

Schick deinen Schlüssel im Header X-API-Key mit. API-Schlüssel sind Zugangsdaten für den Server: Sie gehören nie in Browser-JavaScript oder in eine mobile App.

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

Felder der Anfrage

Feld	Typ	Pflicht	Hinweise
altitude	number (double)	Pflicht
date_time	string (date-time)	Pflicht	Der Zeitpunkt, für den gerechnet wird, im Format ISO 8601. Gib IMMER einen Offset oder ein abschließendes Z an – ein Wert ohne Zone wird als Asia/Kolkata (UTC+05:30) gelesen, nicht als UTC, und kann mit Status 200 das Ergebnis des Vortags liefern. '2026-09-01T06:00:00Z' und '2026-09-01 06:00:00' sind verschiedene Zeitpunkte und ergeben verschiedene Antworten. FORMATVORGABE, kein Enum. DRF DateTimeField: nur ISO-8601 (Standard-Eingabeformate von DRF), z. B. "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" oder "2026-09-01 06:00:00" (ohne Zeitzone wird UTC angenommen).
keys	array	Pflicht	Welche Berechnungen zurückgegeben werden, als Liste von Namen. Siehe die Key-Tabelle dieses Endpoints; ein unbekannter Name lässt die ganze Anfrage scheitern. Ein Aufruf kostet einen Credit, egal wie viele Keys du anforderst – fordere also alles, was du brauchst, auf einmal an, statt mehrere Aufrufe zu machen. `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 von Strings. Die `set_`-Keys ändern Berechnungs-Flags des Celestial-Objekts; die Keys `get_` / `rise_time` / `set_time` / `is_*` liefern Werte.
planet_names	array	Pflicht	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` Array von Strings, Mindestlänge 1. Beachte: Die Mondknoten heißen hier 'MEAN_NODE'/'TRUE_NODE' und nicht wie in der Horoskopausgabe 'northtruenode'. Ein unbekannter Name lässt die Anfrage nicht scheitern; dieser Eintrag lautet dann {"error": "Unknown planet '<X>'"}.
time_zone	number (double)	Pflicht	min -12 · max 14
latitude	number (double)	optional	Breitengrad des Ortes in Dezimalgrad. Positiv ist Nord, negativ ist Süd. Beispiel: 26.9124 für Jaipur, 40.7128 für New York. Minuten und Sekunden werden nicht akzeptiert – vorher umrechnen. min -89.9 · max 89.9
longitude	number (double)	optional	Längengrad des Ortes in Dezimalgrad. Positiv ist Ost, negativ ist West. Beispiel: 75.7873 für Jaipur, -74.0060 für New York. Achte auf das Vorzeichen: Ein fehlendes Minus verlegt New York nach China. min -180 · max 180

Verfügbare Keys (31)

Liste in keys genau die Berechnungen auf, die du brauchst. Ein unbekannter Key lässt die ganze Anfrage scheitern. Du zahlst 1 Credit, ganz gleich, wie viele du anforderst – fass sie also in einer Anfrage zusammen.

Key	Zusätzliche Felder	Beschreibung
get_altitude	date_time, latitude, longitude, altitude	Wie hoch der Himmelskörper über dem Horizont steht, in Grad mit sechs Nachkommastellen; negative Werte liegen unter dem Horizont. Benötigt `latitude`, `longitude` und `altitude` in Metern.
get_apsis	date_time	Das nächste Aphel und Perihel, also der sonnenfernste und der sonnennächste Punkt des Himmelskörpers. Liefert ein Objekt `{Aphelion, Perihelion}` mit je einem UTC-Zeitstempel, ermittelt durch Vorwärtssuche ab dem angegebenen Zeitpunkt. Nur für die Himmelskörper verfügbar, die das Modell abdeckt.
get_azimuth	date_time, latitude, longitude, altitude	In welcher Richtung am Horizont der Himmelskörper zu finden ist, in Grad im Uhrzeigersinn ab Norden, als einzelne Zahl mit sechs Nachkommastellen. Benötigt `latitude`, `longitude` und `altitude` und berücksichtigt die Refraktion, sofern nicht vorher ein Schalter ohne Refraktion gesetzt wurde.
get_declination	date_time	Deklination, also der Winkelabstand des Himmelskörpers nördlich oder südlich des Himmelsäquators, als Objekt aus `degrees`, `minutes` und `seconds`.
get_distance	date_time	Entfernung vom Beobachter in astronomischen Einheiten, auf drei Nachkommastellen gerundet. Eine einzelne Zahl; beim Mond ist das ein kleiner Bruchteil einer AU.
get_ecliptic_speeds	date_time	Wie schnell sich der Himmelskörper bewegt, als Objekt mit `longitude_speed` und `latitude_speed` in Grad pro Tag und `distance_speed` in AU pro Tag, jeweils mit sechs Nachkommastellen. Eine negative Längengeschwindigkeit bedeutet rückläufig.
get_equatorial_speeds	date_time	Bewegung in äquatorialen Koordinaten: ein Objekt mit `right_ascension_speed` und `declination_speed` in Grad pro Tag und `distance_speed` in AU pro Tag, jeweils auf sechs Nachkommastellen.
get_illumination	date_time	Die scheinbare visuelle Helligkeit (Magnitude) des Himmelskörpers zu diesem Zeitpunkt, als einzelne Zahl mit sechs Nachkommastellen – je kleiner bzw. negativer, desto heller. Nur für die Himmelskörper verfügbar, die das Beleuchtungsmodell abdeckt; bei anderen tritt ein Fehler auf.
get_latitude	date_time	Ekliptikale Breite in Grad mit drei Nachkommastellen: wie weit der Himmelskörper über oder unter der Ebene der Ekliptik steht. Eine einzelne Zahl, negativ für Süd.
get_longitude	date_time	Ekliptikale Länge in Grad, 0 bis 360, auf drei Nachkommastellen gerundet – eine einzelne Zahl. Ob sie tropisch oder siderisch ist, hängt vom gerade gültigen Positionsmodus ab.
get_right_ascension	date_time	Rektaszension, das äquatoriale Gegenstück zur Länge, als Objekt aus `hours`, `minutes` und `seconds` statt in Dezimalgrad.
is_retrograde	date_time	Ergibt true, wenn die Längengeschwindigkeit des Himmelskörpers negativ ist, er sich also scheinbar rückwärts durch den Tierkreis bewegt. Ein einzelner boolescher Wert.
is_stationary	date_time	Eine grobe Prüfung auf Stillstand: true, wenn der Nachkommaanteil der täglichen Längengeschwindigkeit auf drei Nachkommastellen gerundet null ergibt. Liefert einen booleschen Wert; wegen dieses Tests ist er nur ein Indiz und keine exakte Station.
rise_time	date_time, geopos	Der Aufgang des Himmelskörpers, gesucht ab lokaler Mitternacht (Offset aus `time_zone`) des angegebenen Datums am Ort. Liefert eine Liste mit zwei Elementen: den Aufgangszeitpunkt als Zeitstempel in der Ortszeit gemäß `time_zone`, danach die rohen Werte des julianischen Tages. Welche Definition von „Aufgang“ gilt, hängt davon ab, welcher Aufgangs- oder Scheibenschalter im Key-Array davor steht. Geht der Körper innerhalb des Suchfensters nicht auf oder unter – der Mond in hohen Breiten oder die Sonne während eines Polartags –, schlägt die zugrunde liegende Suche fehl, und dieser Key liefert "2000-11-24T12:00:00Z", also den julianischen Tag null und keinen echten Zeitpunkt. Behandle genau diesen Wert als „kein Ergebnis“. /api/astro/sunrise/ und /api/astro/moonrise/ liefern in diesem Fall null.
set_astrometric_j_positions	—	Schaltet auf astrometrische Positionen bezogen auf das mittlere Äquinoktium von J2000 um; Nutation, Aberration und Lichtablenkung sind dabei ausgeschaltet. Liefert null.
set_astrometric_positions	—	Schaltet auf astrometrische Positionen um: Die Lichtlaufzeit wird korrigiert, die jährliche Aberration und die gravitative Lichtablenkung jedoch nicht. Liefert null.
set_barycentric_positions	—	Schaltet auf baryzentrische Positionen um, bezogen auf das Baryzentrum des Sonnensystems. Liefert null und funktioniert nur für physische Himmelskörper – nicht für Mondknoten oder Apogäen.
set_default_positions	—	Ein Schalter, kein Wert: setzt scheinbare geozentrische Positionen mit Geschwindigkeiten – das ist der TROPISCHE (TROPICAL) Standard dieses Endpoints. Liefert null. Die `set_*`-Schalter gelten nur für die Keys, die in `keys` nach ihnen stehen; die Reihenfolge ist also wichtig. Setze diesen Schalter an den Anfang oder hinter einen anderen Schalter, um den Standard wiederherzustellen. Beachte: Der gleichnamige Key bei /api/astro/star/ setzt dagegen SIDERISCHE Positionen.
set_default_rising	—	Stellt die Standarddefinition von Auf- und Untergang für `rise_time` und `set_time` wieder her. Ein Schalter, kein Wert – er liefert null und wirkt nur auf die danach aufgeführten Keys.
set_disc_bottom_no_refraction	—	Berechnet Auf- und Untergang am unteren Rand der Scheibe, ohne Refraktion. Liefert null.
set_disc_bottom_refraction	—	Berechnet Auf- und Untergang am unteren Rand der Scheibe, mit atmosphärischer Refraktion. Liefert null.
set_disc_center_no_refraction	—	Berechnet Auf- und Untergang an der Mitte der Scheibe, ohne Refraktion – also geometrisch statt wie beobachtet. Liefert null; spätere `get_azimuth` und `get_altitude` rechnen dann ohne Atmosphäre.
set_disc_center_refraction	—	Berechnet Auf- und Untergang an der Mitte der Scheibe, mit atmosphärischer Refraktion. Liefert null; auch spätere `get_azimuth` und `get_altitude` verwenden dann refraktierte Positionen.
set_heliocentric_positions	—	Schaltet auf heliozentrische Positionen um, bezogen auf den Mittelpunkt der Sonne. Liefert null. Sonne, Mondknoten und Mondapogäen liefern in diesem Modus null.
set_hindu_rising	—	Stellt die Auf- und Untergangszeiten auf die hinduistische Konvention um. Liefert null; wirkt auf die Keys `rise_time` und `set_time`, die im Array danach stehen.
set_jpl_horizons_positions	—	Schaltet auf scheinbare Positionen um, berechnet wie bei JPL Horizons, damit du die Werte mit diesem Dienst abgleichen kannst. Liefert null.
set_mean_equinox_positions	—	Schaltet auf Positionen bezogen auf das mittlere Äquinoktium des Datums um, indem die Nutation abgeschaltet wird. Liefert null.
set_sidereal_positions	—	Schaltet auf siderische Positionen um, also tropische Länge minus Ayanamsa. Liefert null. Das Ayanamsa selbst wird an anderer Stelle festgelegt; es gilt der jeweils aktive siderische Modus.
set_time	date_time, geopos	Der Untergang des Himmelskörpers, gesucht ab lokaler Mitternacht (Offset aus `time_zone`) des angegebenen Datums am Ort. Gleiche Struktur wie `rise_time`: [lokaler Zeitstempel, rohe Werte des julianischen Tages]. Trotz des Präfixes `set_` liefert dieser Key einen Wert und ist kein Schalter. Geht der Körper innerhalb des Suchfensters nicht auf oder unter – der Mond in hohen Breiten oder die Sonne während eines Polartags –, schlägt die zugrunde liegende Suche fehl, und dieser Key liefert "2000-11-24T12:00:00Z", also den julianischen Tag null und keinen echten Zeitpunkt. Behandle genau diesen Wert als „kein Ergebnis“. /api/astro/sunrise/ und /api/astro/moonrise/ liefern in diesem Fall null.
set_topocentric_positions	latitude, longitude, altitude	Schaltet auf topozentrische Positionen um, bezogen auf den Standort des Beobachters statt auf den Erdmittelpunkt. Erfordert `latitude`, `longitude` und `altitude` in Metern; liefert null. Spürbar ist der Unterschied nur beim Mond.
set_true_positions	—	Schaltet auf wahre geometrische Positionen ohne Lichtlaufzeit um – also dorthin, wo der Himmelskörper tatsächlich steht, nicht wo er zu stehen scheint. Liefert null.

Beispielanfrage

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"]}'

Antwort

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

Aus einem echten Aufruf mit genau dieser Anfrage. Die Ergebnisse stehen unter data, jeweils unter dem Key, den du angefordert hast.

Fehler

Abrechnungsfehler liefern { "error": "…", "message": "<code>", "is_error": true }. Zeig deinen Nutzern error an und verzweige im Code anhand von message. Details in der Fehlerreferenz.