Theme natal (occidental)
Theme natal (occidental)
/api/v1/natal/calculateGenerez un theme natal occidental professionnel avec prise en charge de plusieurs systemes de maisons, des vitesses planetaires precises, la detection des stations, des corps supplementaires (asteroides et noeuds) et une gestion explicite des naissances sans heure via time_known.
URL complete
https://api.freeastroapi.com/api/v1/natal/calculateRetenter sans risque avec Idempotency-Key
Les requetes POST astrologiques authentifiees et facturables acceptent l'en-tete optionnel Idempotency-Key: <cle d'operation unique generee cote client>. Reutilisez la meme cle uniquement pour retenter exactement la meme methode, le meme path, la meme query string et le meme corps JSON apres un timeout ou une erreur reseau.
Une relecture terminee renvoie la premiere reponse avec Idempotency-Replayed: true, ne relance pas le calcul et ne consomme pas de quota supplementaire. Les cles sont conservees environ 24 heures.
Reutiliser une cle avec une requete modifiee renvoie 409 idempotency_key_reused. Un doublon pendant que la premiere requete est encore en cours renvoie 409 request_in_progress avec Retry-After.
Parametres du corps de requete
| Parametre | Type | Req | Description |
|---|---|---|---|
| name | string | Non | Nom du sujet (pour l'affichage) |
| year | integer | Oui | Annee de naissance (ex. 1990) |
| month | integer | Oui | Mois de naissance (1-12) |
| day | integer | Oui | Jour de naissance (1-31) |
| time_known | boolean | Non | Par defaut : true. Definissez false lorsque l'heure de naissance est inconnue. Dans ce mode, les maisons et les angles sont omis, les placements des planetes en maisons ne sont pas renvoyes et les metadonnees de confiance sont abaissees. |
| hour | integer | Non | Heure de naissance (0-23, format 24 h). Requise lorsque time_known=true. Ignoree structurellement lorsque time_known=false. |
| minute | integer | Non | Minute de naissance (0-59). Requise lorsque time_known=true. Ignoree structurellement lorsque time_known=false. |
| city | string | Oui | Nom de ville (utilise pour la recherche de coordonnees via /geo/search) |
| lat | float | Non | Latitude (-90 a 90). Optionnel : resolue automatiquement depuis city si absente |
| lng | float | Non | Longitude (-180 a 180). Optionnel : resolue automatiquement depuis city si absente |
| tz_str | string | Non | Fuseau horaire (ex. 'Europe/Paris' ou 'AUTO'). Par defaut : AUTO |
| house_system | string | Non | placidus (default), whole_sign, equal, koch, regiomontanus, porphyry, campanus |
| zodiac_type | string | Non | tropical (par defaut) ou sidereal. Sidereal utilise l'ayanamsa specifie. |
| fixed_stars | array[str] | Non | Selecteur prefere pour les etoiles fixes. Accepte les ids de packs comme royal_4 et behenian_20, les noms exacts comme Spica, ou all pour l'ensemble complet par defaut. Exemple : ["royal_4", "Spica"]. . |
Exemples de code
curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"name": "John Doe",
"year": 1990,
"month": 5,
"day": 15,
"time_known": true,
"hour": 14,
"minute": 30,
"city": "New York",
"lat": 40.7128,
"lng": -74.006,
"tz_str": "AUTO",
"house_system": "placidus",
"zodiac_type": "tropical",
"include_speed": true,
"include_dignity": true,
"include_minor_aspects": true,
"include_stelliums": true,
"fixed_stars": ["royal_4", "Spica"],
"include_features": ["chiron", "lilith", "true_node"],
"interpretation": {
"enable": true,
"style": "improved"
},
"orb_settings": {
"Conjunction": 8.0,
"Opposition": 8.0,
"Trine": 8.0,
"Square": 8.0,
"Sextile": 6.0
}
}'Performance et optimisation v2.2
Compression
Nous prenons en charge la compression Brotli (br) pour une vitesse maximale. Verifiez que votre client envoie Accept-Encoding: br, gzip.
Cache
Les themes natals sont immuables. Les reponses incluent Cache-Control: public, max-age=31536000, immutable. Vous pouvez mettre les resultats en cache indefiniment pour reduire les appels API.
Donnees de reponse
{
"subject": {
"name": "John Doe",
"city": "New York",
"...": "...",
"settings": {
"house_system": "placidus",
"julian_day": 2448032.27083,
"delta_t_days": -0.0000339,
"delta_t_seconds": -2.93,
"zodiac_type": "Tropical",
"time_known": true
}
},
"planets": [
{
"id": "sun",
"name": "Sun",
"sign": "Tau",
"pos": 24.72,
"abs_pos": 54.72,
"house": 9,
"retrograde": false,
"speed": 0.96,
"is_stationary": false
},
{
"id": "moon",
"name": "Moon",
"sign": "Aqu",
"pos": 14.23,
"abs_pos": 314.23,
"house": 5,
"retrograde": false,
"speed": 12.45,
"is_stationary": false
},
{
"id": "chiron",
"name": "Chiron",
"sign": "Can",
"pos": 12.34,
"abs_pos": 102.34,
"house": 11,
"retrograde": false,
"speed": 0.05,
"is_stationary": false
}
// Note: ASC is in "angles" object, not in "planets" array
],
"houses": [
{ "house": 1, "name": "1", "sign": "Can", "sign_id": "cancer", "pos": 8.92, "abs_pos": 98.92 },
{ "house": 2, "name": "2", "sign": "Leo", "sign_id": "leo", "pos": 26.17, "abs_pos": 116.17 },
// ... houses 3-11
{ "house": 12, "name": "12", "sign": "Gem", "sign_id": "gemini", "pos": 9.45, "abs_pos": 69.45 }
],
"angles": {
"asc": 98.92268897761204, // Ascendant: absolute longitude (0-360°)
"mc": 339.333397447316, // Midheaven (MC)
"ic": 159.333397447316, // Imum Coeli (IC) - opposite MC
"dc": 278.92268897761204, // Descendant - opposite ASC
"vertex": 235.34043201194 // Vertex point
},
"angles_details": {
"asc": { "sign": "Can", "sign_id": "cancer", "pos": 8.92268897761204, "abs_pos": 98.92268897761204, "house": 1 },
"mc": { "sign": "Pis", "sign_id": "pisces", "pos": 9.333397447316, "abs_pos": 339.333397447316, "house": 10 },
"ic": { "sign": "Vir", "sign_id": "virgo", "pos": 9.333397447316, "abs_pos": 159.333397447316, "house": 4 },
"dc": { "sign": "Cap", "sign_id": "capricorn", "pos": 8.92268897761204, "abs_pos": 278.92268897761204, "house": 7 },
"vertex": { "sign": "Sco", "sign_id": "scorpio", "pos": 25.34043201194, "abs_pos": 235.34043201194, "house": 5 }
},
"aspects": [
{
"p1": "Sun",
"p2": "Moon",
"type": "Square",
"orb": 5.51,
"deg": 90.0,
"is_major": true
}
],
"stelliums": {
"threshold": 3,
"signs": [
{ "sign_id": "taurus", "count": 3, "bodies": ["mercury", "sun", "venus"] }
],
"houses": [],
"total": 1
},
"fixed_stars": {
"Regulus": {
"id": "fixed_star_regulus",
"name": "Regulus",
"sign": "Leo",
"sign_id": "leo",
"pos": 29.7,
"abs_pos": 149.7,
"house": 2
}
},
"confidence": {
"houses": "high",
"angles": "high",
"overall": "high"
},
"interpretation": {
"metadata": {
"key_count": 57,
"found_count": 57,
"missing_keys": []
},
"sections": {
"core_self": [
{
"id": "b86f87d3-2ea7-4dba-b1be-a667f4435584",
"key": "planet.sun.sign.taurus",
"category": "planet_sign",
"title": "Sun in Taurus",
"body": "Sun in Taurus emphasizes steadiness, material awareness, and a measured approach to life...",
"tone": "improved",
"tags": ["sun", "taurus"],
"created_at": "2026-02-04T09:10:16.104443+00:00",
"updated_at": "2026-02-04T09:10:16.104443+00:00"
}
],
"mind": [
{
"id": "fdea3513-56db-4349-b55e-87cb382ab520",
"key": "planet.mercury.sign.taurus",
"category": "planet_sign",
"title": "Mercury in Taurus",
"body": "Mercury in Taurus shapes a steady, deliberate mind...",
"tone": "improved",
"tags": ["mercury", "taurus"],
"created_at": "2026-02-04T09:11:25.614751+00:00",
"updated_at": "2026-02-04T09:11:25.614751+00:00"
}
],
"love_relating": [],
"work_path": [],
"social_collective": [],
"karmic_healing": [
{
"id": "9ae37083-cadc-4a57-b3ac-7ec99645f0eb",
"key": "planet.chiron.sign.cancer",
"category": "planet_sign",
"title": "Chiron in Cancer",
"body": "Chiron in Cancer highlights a longstanding sensitivity around belonging...",
"tone": "improved",
"tags": ["chiron", "cancer"],
"created_at": "2026-02-04T09:26:12.302848+00:00",
"updated_at": "2026-02-04T09:26:12.302848+00:00"
}
],
"aspects": [
{
"p1": "moon",
"p2": "sun",
"type": "trine",
"key": "aspect.moon.trine.sun",
"title": "Sun Trine Moon",
"content": "Sun trine Moon reflects an easy flow between instinct and intention..."
}
]
}
}
} Exemple de reponse sans heure
{
"subject": {
"name": "Jane Doe",
"settings": {
"house_system": "placidus",
"zodiac_type": "Tropical",
"time_known": false
}
},
"planets": [
{
"id": "sun",
"name": "Sun",
"sign": "Sco",
"sign_id": "scorpio",
"pos": 10.84,
"abs_pos": 220.84,
"retrograde": false
},
{
"id": "north_node",
"name": "North Node",
"sign": "Sag",
"sign_id": "sagittarius",
"pos": 2.18,
"abs_pos": 242.18,
"retrograde": true,
"variant": "true"
},
{
"id": "chiron",
"name": "Chiron",
"sign": "Leo",
"sign_id": "leo",
"pos": 14.02,
"abs_pos": 134.02,
"retrograde": false
}
],
"aspects": [
{
"p1": "moon",
"p2": "sun",
"type": "trine",
"orb": 1.42,
"deg": 120,
"is_major": true
}
],
"confidence": {
"houses": "unavailable",
"angles": "unavailable",
"overall": "medium"
}
}FAQ
Cet endpoint fournit-il une carte visuelle en SVG ou PNG ?
Non. L'endpoint Natal renvoie uniquement les donnees calculees du theme ; il ne genere pas d'images de carte en SVG ou PNG. Utilisez l'endpoint Western Chart SVG lorsque vous avez besoin d'une carte visuelle.
Votre API renvoie-t-elle les paralleles ?
Oui. L'endpoint Natal peut renvoyer les paralleles et contre-paralleles de declinaison lorsque vous les activez avec"include_declination_aspects": true. Ils ne sont pas renvoyes par defaut.
{
"include_declination_aspects": true,
"declination_orb": 1.0
}Les resultats sont renvoyes sous declination_aspects et resumes dansdeclination_aspects_summary. Les aspects de longitude classiques restent sousaspects.