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

Étoiles fixes

Les données de position d’une étoile fixe désignée par son nom, tirées du catalogue standard des étoiles fixes. L’astrologie védique comme l’occidentale prennent quelques étoiles brillantes comme repères — Aldébaran, Régulus, Spica, Antarès — et les nakshatras portent eux-mêmes le nom de leurs yogataras, les étoiles de jonction qui les définissent. Cet endpoint donne les coordonnées écliptiques et équatoriales d’une étoile, la vitesse à laquelle elles varient, ainsi que sa luminosité. Envoyez `name` sous forme de nom traditionnel (`Aldebaran`, `Regulus`) ou de désignation de Bayer (`alTau`, `alLeo`) ; la correspondance ignore la casse et les espaces, et une virgule initiale impose la forme de Bayer. Ajoutez `date_time`, `timezone_as_float` et les `keys` souhaitées. Important : mettez `set_default_positions` en première position dans `keys`. Les clés s’exécutent dans l’ordre où vous les donnez, et toutes les clés de position dépendent des indicateurs de calcul que cet appel installe — sans lui, elles échouent. Seule `magnitude`, qui vient directement du catalogue, fonctionne sans lui. Les positions sont sidérales. `latitude` et `longitude` sont acceptés mais pas utilisés : la position géocentrique d’une étoile fixe ne dépend pas de l’endroit où l’on se trouve.

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

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
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.
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.
name	string	obligatoire	`AldebaranRohiniAlgolAntaresRegulusSiriusSpicaTrappist-1Galactic CenterGal. CenterGreat AttractorVirgo Cluster` Une étoile fixe du catalogue standard des étoiles fixes : soit un nom traditionnel (Aldebaran, Regulus, Spica), soit une désignation de Bayer (alTau, alLeo). La correspondance ignore la casse et les espaces. Ajoutez une virgule en préfixe pour forcer la forme de Bayer, p. ex. ',alTau'. Environ 735 noms traditionnels et 1117 désignations sont disponibles, y compris des points non stellaires tels que Galactic Center. Un nom non reconnu renvoie une erreur 400.
timezone_as_float	number (double)	obligatoire	Décalage UTC du lieu, en heures, sous forme décimale. Exemple : 5.5 pour l’Inde (UTC+05:30), -5 pour New York en hiver, 5.75 pour le Népal. Cette valeur n’est PAS contrôlée par rapport à date_time - si les deux divergent, vous obtenez une réponse réussie pour le mauvais moment ; tirez donc les deux de la même source. Utilisez le décalage en vigueur à cette date, pas celui d’aujourd’hui : une naissance en été dans un pays qui applique l’heure d’été exige le décalage d’été. 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 (10)

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
declination	date_time	La déclinaison de l’étoile à `date_time`, son angle au nord ou au sud de l’équateur céleste, renvoyée sous la forme `{degrees, minutes, seconds}`. La conversion prend la valeur absolue : le signe est donc perdu et une déclinaison sud ne se distingue pas d’une déclinaison nord — tirez l’hémisphère de la position de l’étoile dans le catalogue si vous en avez besoin.
distance	date_time	La distance de l’étoile à la Terre à `date_time`, un seul nombre en unités astronomiques arrondi à trois décimales.
ecliptic_speeds	date_time	La vitesse de variation des coordonnées écliptiques de l’étoile à `date_time`, sous la forme `{longitude_speed, latitude_speed, distance_speed}` — les deux premières en degrés par jour, la dernière en unités astronomiques par jour. Les valeurs sont infimes, car le mouvement apparent d’une étoile fixe relève de la précession et du mouvement propre plutôt que d’un mouvement orbital.
equatorial_speeds	date_time	La vitesse de variation des coordonnées équatoriales de l’étoile à `date_time`, sous la forme `{right_ascension_speed, declination_speed, distance_speed}` — les deux premières en degrés par jour, la dernière en unités astronomiques par jour.
latitude	date_time	La latitude écliptique de l’étoile à `date_time` — son écart au nord ou au sud du plan de l’écliptique — sous forme d’un seul nombre de degrés arrondi à trois décimales, négatif au sud. C’est ce qui écarte une étoile de la bande zodiacale, et c’est pourquoi certaines étoiles brillantes ne sont jamais en conjonction exacte avec une planète.
longitude	date_time	La longitude écliptique sidérale de l’étoile à `date_time` : un seul nombre de degrés de 0 à 360, arrondi à trois décimales.
magnitude	—	La magnitude visuelle apparente de l’étoile selon le catalogue, un seul nombre ; plus il est bas, plus l’étoile est brillante : Aldébaran renvoie ainsi 0.86. C’est la seule clé de l’endpoint qui ne demande ni date ni appel préalable à `set_default_positions`.
retrograde	date_time	Indique si la longitude écliptique de l’étoile décroît à `date_time` : un seul booléen, qui vaut true lorsque `longitude_speed` est négatif. Pour une étoile fixe, il vaut en pratique toujours false, car la précession la fait avancer dans le zodiaque sidéral.
right_ascension	date_time	L’ascension droite de l’étoile à `date_time`, sa coordonnée est-ouest sur l’équateur céleste, renvoyée sous la forme `{hours, minutes, seconds}` plutôt qu’en degrés décimaux.
set_default_positions	—	Un commutateur, pas une valeur : active les positions géocentriques apparentes avec vitesses et, contrairement à la clé du même nom sur /api/astro/celestial/, active aussi l’indicateur SIDÉRAL - par défaut, cet endpoint est donc sidéral, et non tropical. Renvoie null. Placez cette clé en premier dans `keys` : les commutateurs ne s’appliquent qu’aux clés listées après eux.

Exemple de requête

curl -X POST https://api.occultapi.com/api/astro/star/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2026-09-01T06:00:00+05:30","timezone_as_float":5.5,"latitude":26.9124,"longitude":75.7873,"name":"Aldebaran","keys":["set_default_positions","magnitude"]}'

Réponse

{
  "data": {
    "set_default_positions": null,
    "magnitude": 0.86
  },
  "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.