POST/api/astro/celestial/1 crédit

Positions célestes

Éphémérides brutes pour un ou plusieurs corps : où se trouve une planète, à quelle vitesse elle se déplace, quand elle se lève et se couche, si elle est rétrograde. C’est la couche astronomique sur laquelle repose le reste de l’API, exposée telle quelle, et elle va bien au-delà des neuf grahas védiques : planètes extérieures, Chiron et astéroïdes, points fictifs uraniens et plusieurs lunes planétaires sont tous accessibles. Les clés sont de deux sortes. Les clés `set_*` sont des commutateurs : elles changent le mode de calcul des positions ou des heures de lever et de coucher — géocentrique, topocentrique ou héliocentrique, apparent ou vrai, avec ou sans nutation, sidéral ou tropical, lever hindou ou lever au centre du disque — et chacune renvoie null. Les clés `get_*`, ainsi que `rise_time`, `set_time`, `is_retrograde` et `is_stationary`, renvoient des valeurs. Les clés étant exécutées dans l’ordre où vous les listez, un commutateur n’agit que sur les clés de valeur placées après lui dans le tableau. `planet_names` prend une liste de noms en majuscules, et la réponse est indexée par ces noms : un appel pour MARS renvoie donc `{"data": {"MARS": {"get_longitude": 123.45}}}`. Un nom non reconnu ne fait pas échouer la requête : l’entrée correspondante vaut `{"error": "Unknown planet '<name>'"}`. Notez qu’ici les nœuds s’appellent MEAN_NODE et TRUE_NODE, et non 'northtruenode' comme dans /api/astro/chart/.

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

Tester la requête

Authentification

Envoyez votre clé dans l’en-tête X-API-Key. Une clé est un identifiant côté serveur : ne la placez jamais dans du JavaScript exécuté par le navigateur ni dans une application mobile.

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

Champs de la requête

Champ	Type	Obligatoire	Remarques
altitude	number (double)	obligatoire
date_time	string (date-time)	obligatoire	Le moment du calcul, en ISO 8601. Incluez TOUJOURS un décalage ou un Z final - une valeur sans fuseau est lue comme Asia/Kolkata (UTC+05:30), et non comme UTC, et peut renvoyer le résultat de la veille avec un statut 200. '2026-09-01T06:00:00Z' et '2026-09-01 06:00:00' sont des instants différents et donnent des réponses différentes. Contrainte de FORMAT, pas une énumération. DateTimeField DRF : ISO-8601 uniquement (formats d’entrée par défaut de DRF), p. ex. "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" ou "2026-09-01 06:00:00" (sans fuseau = UTC supposé).
keys	array	obligatoire	Les calculs à renvoyer, sous forme de liste de noms. Consultez le tableau des clés de cet endpoint ; un nom non reconnu fait rejeter toute la requête. Un appel coûte un crédit quel que soit le nombre de clés demandées : demandez donc tout ce dont vous avez besoin en une seule fois plutôt que de faire plusieurs appels. `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` Tableau de chaînes. Les clés `set_` modifient des indicateurs de calcul sur l’objet Celestial ; les clés `get_` / `rise_time` / `set_time` / `is_*` renvoient des valeurs.
planet_names	array	obligatoire	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` Tableau de chaînes, longueur minimale 1. Notez qu’ici les nœuds s’appellent 'MEAN_NODE'/'TRUE_NODE', et non 'northtruenode' comme dans la sortie des thèmes. Un nom non reconnu ne fait pas échouer la requête : l’entrée correspondante vaut {"error": "Unknown planet '<X>'"}.
time_zone	number (double)	obligatoire	min -12 · max 14
latitude	number (double)	facultatif	Latitude du lieu, en degrés décimaux. Positive au nord, négative au sud. Exemple : 26.9124 pour Jaipur, 40.7128 pour New York. Les minutes et les secondes ne sont pas acceptées - convertissez d’abord. min -89.9 · max 89.9
longitude	number (double)	facultatif	Longitude du lieu, en degrés décimaux. Positive à l’est, négative à l’ouest. Exemple : 75.7873 pour Jaipur, -74.0060 pour New York. Attention au signe : sans le moins, New York se retrouve en Chine. min -180 · max 180

Clés disponibles (31)

Listez dans keys exactement les calculs voulus. Une clé inconnue fait rejeter toute la requête. Vous payez 1 crédit, quel que soit le nombre de clés demandées : regroupez-les donc.

Clé	Champs supplémentaires requis	Description
get_altitude	date_time, latitude, longitude, altitude	Hauteur du corps au-dessus de l’horizon, en degrés à six décimales ; une valeur négative signifie qu’il est sous l’horizon. Nécessite `latitude`, `longitude` et `altitude` en mètres.
get_apsis	date_time	Les prochains aphélie et périhélie, c’est-à-dire les points où le corps est le plus loin et le plus près du Soleil. Renvoie un objet `{Aphelion, Perihelion}` avec une date-heure UTC pour chacun, trouvée en cherchant vers l’avant à partir du moment donné. Disponible uniquement pour les corps couverts par le modèle.
get_azimuth	date_time, latitude, longitude, altitude	Direction dans laquelle chercher le corps sur l’horizon, en degrés dans le sens horaire depuis le nord, sous forme d’un seul nombre à six décimales. Nécessite `latitude`, `longitude` et `altitude`, et tient compte de la réfraction, sauf si un commutateur sans réfraction a été placé avant.
get_declination	date_time	La déclinaison, soit la distance angulaire du corps au nord ou au sud de l’équateur céleste, sous forme d’objet `degrees`, `minutes` et `seconds`.
get_distance	date_time	Distance à l’observateur en unités astronomiques, arrondie à trois décimales. Un seul nombre ; pour la Lune, c’est une petite fraction d’AU.
get_ecliptic_speeds	date_time	Vitesse de déplacement du corps, sous forme d’objet avec `longitude_speed` et `latitude_speed` en degrés par jour et `distance_speed` en AU par jour, chacune à six décimales. Une vitesse en longitude négative signifie que le corps est rétrograde.
get_equatorial_speeds	date_time	Le mouvement en coordonnées équatoriales : un objet avec `right_ascension_speed` et `declination_speed` en degrés par jour et `distance_speed` en AU par jour, chacune à six décimales.
get_illumination	date_time	Magnitude visuelle apparente du corps à ce moment, sous forme d’un seul nombre à six décimales — plus elle est petite (et négative), plus le corps est brillant. Disponible uniquement pour les corps couverts par le modèle de luminosité ; pour les autres, une erreur est levée.
get_latitude	date_time	Latitude écliptique en degrés, à trois décimales : l’écart du corps au-dessus ou au-dessous du plan de l’écliptique. Un seul nombre, négatif vers le sud.
get_longitude	date_time	Longitude écliptique en degrés, de 0 à 360, arrondie à trois décimales — un seul nombre. Elle est tropicale ou sidérale selon le mode de position en vigueur.
get_right_ascension	date_time	L’ascension droite, l’équivalent équatorial de la longitude, sous forme d’objet `hours`, `minutes` et `seconds` plutôt qu’en degrés décimaux.
is_retrograde	date_time	Vaut true lorsque la vitesse en longitude du corps est négative, c’est-à-dire lorsqu’il semble reculer dans le zodiaque. Un seul booléen.
is_stationary	date_time	Test de stationnarité approximatif : vaut true lorsque la partie fractionnaire de la vitesse quotidienne en longitude du corps s’arrondit à zéro à trois décimales. Renvoie un booléen ; vu la méthode, c’est un indicateur et non la détection exacte d’une station.
rise_time	date_time, geopos	Le lever du corps, recherché à partir de minuit heure locale (selon le décalage de `time_zone`) à la date donnée, au lieu indiqué. Renvoie une liste de deux éléments : le moment du lever, en date-heure dans l’heure locale définie par `time_zone`, puis les valeurs brutes en jours juliens. La définition du « lever » appliquée dépend du commutateur de lever ou de disque placé avant dans le tableau des clés. Si le corps ne se lève pas ou ne se couche pas dans la fenêtre de recherche - la Lune à haute latitude, ou le Soleil pendant un jour polaire -, la recherche sous-jacente échoue et cette clé renvoie "2000-11-24T12:00:00Z", soit le jour julien zéro, et non un instant réel. Traitez cette valeur exacte comme une absence de résultat. /api/astro/sunrise/ et /api/astro/moonrise/ renvoient null dans le même cas.
set_astrometric_j_positions	—	Passe en positions astrométriques rapportées à l’équinoxe moyen de J2000, sans nutation, sans aberration et sans déflexion de la lumière. Renvoie null.
set_astrometric_positions	—	Passe en positions astrométriques : le temps de trajet de la lumière est corrigé, mais ni l’aberration annuelle ni la déflexion gravitationnelle de la lumière. Renvoie null.
set_barycentric_positions	—	Passe en positions barycentriques, rapportées au barycentre du système solaire. Renvoie null, et ne fonctionne que pour les corps physiques — pas pour les nœuds ni les apogées.
set_default_positions	—	Un commutateur, pas une valeur : sélectionne les positions géocentriques apparentes avec vitesses, soit le réglage TROPICAL par défaut de cet endpoint. Renvoie null. Les commutateurs `set_*` ne s’appliquent qu’aux clés listées après eux dans `keys`, l’ordre compte donc - placez celui-ci en premier, ou après un autre commutateur pour revenir au réglage par défaut. Notez que la clé du même nom sur /api/astro/star/ sélectionne au contraire des positions SIDÉRALES.
set_default_rising	—	Rétablit la définition par défaut du lever et du coucher pour `rise_time` et `set_time`. Un commutateur, pas une valeur — il renvoie null et n’affecte que les clés listées après lui.
set_disc_bottom_no_refraction	—	Calcule le lever et le coucher à partir du bord inférieur du disque, sans réfraction. Renvoie null.
set_disc_bottom_refraction	—	Calcule le lever et le coucher à partir du bord inférieur du disque, avec réfraction atmosphérique. Renvoie null.
set_disc_center_no_refraction	—	Calcule le lever et le coucher à partir du centre du disque, sans réfraction — des heures géométriques plutôt qu’observées. Renvoie null ; tout `get_azimuth` ou `get_altitude` placé ensuite est aussi calculé sans atmosphère.
set_disc_center_refraction	—	Calcule le lever et le coucher à partir du centre du disque, avec réfraction atmosphérique. Renvoie null ; tout `get_azimuth` ou `get_altitude` placé ensuite utilise aussi des positions corrigées de la réfraction.
set_heliocentric_positions	—	Passe en positions héliocentriques, rapportées au centre du Soleil. Renvoie null. Dans ce mode, le Soleil, les nœuds lunaires et les apogées lunaires valent zéro.
set_hindu_rising	—	Applique la convention hindoue aux heures de lever et de coucher. Renvoie null ; agit sur les clés `rise_time` et `set_time` placées après ce commutateur dans le tableau.
set_jpl_horizons_positions	—	Passe en positions apparentes calculées à la manière de JPL Horizons, pour pouvoir comparer avec ce service. Renvoie null.
set_mean_equinox_positions	—	Passe en positions rapportées à l’équinoxe moyen de la date, en désactivant la nutation. Renvoie null.
set_sidereal_positions	—	Passe en positions sidérales, c’est-à-dire la longitude tropicale moins l’ayanamsa. Renvoie null. L’ayanamsa lui-même se règle ailleurs : c’est donc le mode sidéral en vigueur qui s’applique.
set_time	date_time, geopos	Le coucher du corps, recherché à partir de minuit heure locale (selon le décalage de `time_zone`) à la date donnée, au lieu indiqué. Même structure que `rise_time` : [date-heure locale, valeurs brutes en jours juliens]. Malgré le préfixe `set_`, cette clé renvoie une valeur : ce n’est pas un commutateur. Si le corps ne se lève pas ou ne se couche pas dans la fenêtre de recherche - la Lune à haute latitude, ou le Soleil pendant un jour polaire -, la recherche sous-jacente échoue et cette clé renvoie "2000-11-24T12:00:00Z", soit le jour julien zéro, et non un instant réel. Traitez cette valeur exacte comme une absence de résultat. /api/astro/sunrise/ et /api/astro/moonrise/ renvoient null dans le même cas.
set_topocentric_positions	latitude, longitude, altitude	Passe en positions topocentriques, rapportées au lieu même de l’observateur plutôt qu’au centre de la Terre. Nécessite `latitude`, `longitude` et `altitude` en mètres ; renvoie null. La différence n’est sensible que pour la Lune.
set_true_positions	—	Passe en positions géométriques vraies, sans correction du temps de trajet de la lumière — là où le corps se trouve réellement, et non là où il paraît être. Renvoie null.

Exemple de requête

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

Réponse

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

Réponse capturée lors d’un vrai appel, avec exactement la requête ci-dessus. Les résultats se trouvent dans data, sous le nom de chaque clé demandée.

Erreurs

Les erreurs du contrôle de clé et de crédits renvoient { "error": "…", "message": "<code>", "is_error": true }. Affichez error à vos utilisateurs et basez votre logique sur message. Voir la référence des erreurs.