Méthodologie

Les positions planétaires sont calculées à partir des éphémérides NASA JPL : le jeu de données complet de 105 Mo, et non une version allégée, avec 735 étoiles fixes, couvrant la période 500–2999 apr. J.-C. Rien n’est interpolé depuis une table de valeurs d’almanach précalculées, et aucun résultat n’est mis en cache : chaque réponse est calculée pour l’instant et les coordonnées exacts de la requête.

Cette étendue compte dans deux cas bien réels : les thèmes historiques, et les analyses de dashas et de transits à long terme qui s’étendent sur des décennies au-delà d’aujourd’hui. Une bibliothèque limitée à l’époque moderne perd en qualité aux extrémités, sans le signaler.

Le même moteur de calcul fait tourner Yoga Panchang, notre site gratuit de panchang et de Jyotish : les chiffres que ses lecteurs consultent chaque jour proviennent donc du code décrit ici.

Entre deux calculs védiques, la principale source d’écart n’est pas l’arithmétique, c’est l’ayanamsa. Les traditions indiennes divergent réellement sur ce point, et un écart d’un degré peut faire passer une planète d’un nakshatra à l’autre.

Nous en proposons donc 48 (la famille Surya Siddhanta, True Citra, True Revati, True Pushya, Raman, KP, Yukteshwar et les autres) et vous permettons de corriger chacun en degrés, minutes et secondes. Nous n’en livrons pas un seul en le déclarant juste. Si notre résultat diffère d’une autre source, vérifiez d’abord que vous utilisez tous les deux le même ayanamsa.

C’est ce que la plupart des documentations d’API ne peuvent pas revendiquer. Notre référence n’est pas écrite à la main : elle est générée à partir des sérialiseurs eux-mêmes par build_api_catalogue, puis validée sur un serveur en service par verify_api_catalogue, qui envoie chaque exemple de requête documenté et vérifie qu’il renvoie un code 2xx.

Le résultat est précieux : 255 des 299 pages d’endpoints affichent une vraie réponse enregistrée, et non une réponse inventée ; les autres sont signalées comme pas encore vérifiées, au lieu d’être présentées comme fonctionnelles. Un champ ne peut pas disparaître discrètement de la documentation, comme cela arrive dans un tableur tenu à la main. Si un sérialiseur change sans que la documentation soit régénérée, la vérification échoue plutôt que de publier un mensonge.

Le même catalogue génère la spécification OpenAPI, la collection Postman et llms.txt : les quatre décrivent donc la même API, par construction.

Le back-end compte 1 783 fonctions de test réparties sur 87 modules. La facturation à l’usage est la plus testée, car c’est là qu’une erreur coûte de l’argent à quelqu’un : un appel réussi débite exactement le coût de l’endpoint, une erreur 4xx ou 5xx ne débite rien, une course concurrente pour le dernier crédit ne peut pas rendre un solde négatif, et le registre concorde avec le solde après une suite aléatoire d’attributions et de dépenses.

Nous annonçons 62 ms en médiane et 76 % sous les 100 ms. Ces chiffres viennent de l’appel de 254 exemples publiés le 22 octobre 2026, chacun avec sa propre requête d’exemple, sur une instance locale de l’API — une première fois pour l’échauffement, puis une fois chronométrée. Pas du chronométrage d’un endpoint rapide, arrondi ensuite. Le chat IA est exclu : son temps est celui du modèle de langage.

C’est pourquoi nous précisons aussi ceci : quelques endpoints sont beaucoup plus lents, et la documentation le dit. Un balayage complet du varshaphal ou une année de raasi dasha se compte en secondes, pas en millisecondes, car il s’agit d’une analyse et non d’une simple consultation. Une médiane le masque ; publier la distribution à côté, non.

médiane  62 ms      la moitié des endpoints sont plus rapides
<100ms   76%        l’essentiel des consultations courantes
lents    secondes    analyses lourdes, signalées dans la référence

Deux choses que nous aimerions publier et que nous n’avons pas encore publiées. Nous le disons clairement plutôt que de vous laisser le supposer :

• Un banc d’essai indépendant des positions. Nous calculons à partir des éphémérides JPL, mais nous n’avons pas encore publié de comparaison de nos résultats avec JPL Horizons sur un éventail de dates et de corps célestes, avec les écarts et le code pour les reproduire. D’ici là, comprenez notre affirmation de précision comme « calculé à partir de cette source », et non comme « vérifié avec cette tolérance ».
• La disponibilité sur la durée. La disponibilité n’est publiée sur la page de statut que depuis octobre 2026, il n’y a donc pas encore de long historique à citer. Consultez la page transparence pour savoir à quoi nous nous engageons.

Les deux sont prévus. Aucun n’est difficile ; ce sont deux chantiers que nous préférons faire correctement plutôt qu’approximativement.

Le Playground lance de vrais appels avec votre propre clé, et un appel en échec ne coûte rien : vous pouvez comparer nos résultats à la source en laquelle vous avez déjà confiance. Si vous trouvez un écart que l’ayanamsa n’explique pas, nous voulons le savoir.