Introduction

Le panchang et ses cinq éléments, la kundli et les cartes divisionnaires de D2 à D60, trente systèmes de dashas, les yogas et les doshas, les fenêtres de muhurat, l’ashtakavarga, la force des planètes, la compatibilité entre thèmes, la numérologie selon treize systèmes, et onze calendriers régionaux avec leurs fêtes.

Tout est calculé pour la date, l’heure et les coordonnées de votre requête. Il n’y a pas d’almanach en cache. Presque tous les endpoints renvoient des nombres et des classifications classiques, pas des interprétations rédigées. Quelques-uns renvoient du texte : l’endpoint de chat, les prévisions générales, le rashifal et les rapports PDF.

L’essentiel de l’API se comporte comme vous vous y attendez. Ces trois points font exception, et ce sont eux qui font perdre du temps.

Beaucoup d’endpoints acceptent un tableau keys qui liste les calculs voulus. Un seul appel à /api/astro/panchanga/ peut renvoyer n’importe lequel de 57 résultats différents, selon ce que vous demandez.

Tous coûtent le même et unique crédit. Tout demander en un seul appel est la solution économique, pas la plus chère : l’erreur, c’est d’appeler cinq fois le même endpoint pour cinq clés. Chaque page d’endpoint liste ses clés valides, et la référence se consulte par calcul comme par route : vous trouvez la fonctionnalité sans savoir quel endpoint la fournit.

{
  "date_time": "2026-09-16T06:00:00+05:30",
  "latitude": 26.9124,
  "longitude": 75.7873,
  "timezone_as_float": 5.5,
  "keys": ["tithi", "nakshatra_segments", "yogam", "karana", "vaara"]
}

Chaque réponse JSON contient les quatre mêmes champs. Testez is_error, lisez data et affichez message en cas de problème : il nomme les champs fautifs au lieu d’un vague « requête invalide ».

{
  "data":     { ... },        // the result; shape varies by endpoint
  "status":   200,
  "is_error": false,
  "message":  "successful"
}

Un crédit par appel réussi ; les deux rapports PDF et l’endpoint de chat coûtent 25 crédits. Une erreur 4xx, une erreur 5xx ou un délai dépassé ne coûte rien : le crédit est réservé avant le calcul et libéré si celui-ci n’aboutit pas proprement. Une intégration défaillante ne peut pas vider votre solde pendant que vous la déboguez.

L’accès se fait par une formule mensuelle ou annuelle. Son quota est remis à zéro chaque mois, et les appels non utilisés ne sont pas reportés. Pas de facturation par utilisateur, et vous pouvez résilier à tout moment. Chaque réponse contient X-Credits-Charged et X-Credits-Remaining : vous suivez votre solde sans second appel.

Les positions viennent des éphémérides NASA JPL : le jeu de données complet, 735 étoiles fixes, testé de 500 à 2999 apr. J.-C. Le temps de réponse médian côté serveur est de 62 ms, mesuré sur tous les exemples publiés et non sur un exemple choisi ; les endpoints lents sont des recherches approfondies, et la documentation le signale.

Les traditions indiennes divergent réellement sur l’ayanamsa. L’API en propose donc 48 et vous permet de corriger chacun au degré, à la minute et à la seconde près. Le choix vous revient, tout comme son explication à vos utilisateurs : nous ne le faisons pas à votre place en imposant un ayanamsa présenté comme le bon.

C’est un outil de calcul, pas de conseil. Rien de ce qu’elle renvoie ne constitue un avis médical, juridique ou financier et, hormis les quelques endpoints qui renvoient du texte, elle ne rédige aucune interprétation. Si votre produit en tire des recommandations, c’est votre choix éditorial : consultez la licence pour savoir ce que vous pouvez faire des résultats.

L’URL de base est https://api.occultapi.com. Au-delà du simple HTTP, vous disposez d’un Playground qui exécute de vrais appels avec votre propre clé (un appel en échec ne coûte rien), d’une collection Postman, d’une spécification OpenAPI 3.1 pour générer un client, et d’un serveur MCP pour qu’un assistant IA appelle l’API directement.