API Thème Natal | Documentation FreeAstroAPI

Thème natal (occidental)

POST/api/v1/natal/calculate

Générez un thème natal occidental professionnel avec prise en charge de plusieurs systèmes de maisons, des vitesses planétaires précisés, la détection des stations, des corps supplementaires (asteroides et noeuds) et une gestion explicite des naissances sans heure via time_known.

URL complète

https://api.freeastroapi.com/api/v1/natal/calculate

Retenter 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.

Paramètres du corps de requête

Paramètre	Type	Req	Description
name	string	Non	Nom du sujet (pour l'affichage)
year	integer	Oui	Année 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 défaut : true. Définissez false lorsque l'heure de naissance est inconnue. Dans ce mode, les maisons et les angles sont omis, les placements des planètes en maisons ne sont pas renvoyés et les métadonnées de confiance sont abaissees.
hour	integer	Non	Heure de naissance (0-23, format 24 h). Requise lorsque time_known=true. Ignorée structurellement lorsque time_known=false.
minute	integer	Non	Minute de naissance (0-59). Requise lorsque time_known=true. Ignorée structurellement lorsque time_known=false.
city	string	Oui	Nom de ville (utilise pour la recherche de coordonnées via /geo/search)
lat	float	Non	Latitude (-90 à 90). Optionnel : résolue automatiquement depuis city si absente
lng	float	Non	Longitude (-180 à 180). Optionnel : résolue automatiquement depuis city si absente
tz_str	string	Non	Fuseau horaire (ex. 'Europe/Paris' ou 'AUTO'). Par défaut : AUTO
house_system	string	Non	placidus (default), whole_sign, equal, koch, regiomontanus, porphyry, campanus
zodiac_type	string	Non	tropical (par défaut) ou sidereal. Sidereal utilise l'ayanamsa specifie.
fixed_stars	array[str]	Non	Sélecteur prefere pour les étoiles fixes. Accepte les ids de packs comme `royal_4` et `behenian_20`, les noms exacts comme `Spica`, ou `all` pour l'ensemble complet par défaut. 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. Vérifiez que votre client envoie Accept-Encoding: br, gzip.

Cache

Les thèmes natals sont immuables. Les réponses incluent Cache-Control: public, max-age=31536000, immutable. Vous pouvez mettre les resultats en cache indefiniment pour réduire les appels API.

Données de réponse

{
  "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 réponse 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 données calculees du thème ; il ne génère 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 parallèles ?

Oui. L'endpoint Natal peut renvoyer les parallèles et contre-parallèles de déclinaison lorsque vous les activez avec"include_declination_aspects": true. Ils ne sont pas renvoyés par défaut.

{
  "include_declination_aspects": true,
  "declination_orb": 1.0
}

Les resultats sont renvoyés sous declination_aspects et résumés dansdeclination_aspects_summary. Les aspects de longitude classiques restent sousaspects.

Endpoints associés

Transits

Comparer le ciel actuel a un thème natal

Thème vedique

Calculs sideraux (Lahiri)