API de thème astral

URL de base : https://api.natalchart.ai. Chaque requête porte une clé API, chaque réponse est en JSON, et chaque longitude est donnée à quatre décimales de degré avant d’être convertie en signe. La clé est gratuite : connectez-vous avec un compte NatalChart.AI et créez-en une.

Démarrage rapide

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

La réponse, pour les données de naissance de démonstration utilisées sur tout le site (1991-09-06, 18:30, Kyiv). Cinq des corps sont affichés :

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

Serveur MCP pour assistants IA

Les mêmes calculs sont disponibles sous forme de serveur MCP à l’adresse https://www.natalchart.ai/mcp, pour Claude, ChatGPT, Cursor et VS Code. Il prend la même clé et puise dans le même quota quotidien, à raison d’une requête par appel d’outil. Configuration pour chaque client : Serveur MCP pour assistants IA.

Authentification

Envoyez la clé sous la forme Authorization: Bearer nc_live_... (un en-tête X-API-Key fonctionne aussi). La clé complète n’est affichée qu’une fois, à sa création ; nous n’en conservons que le hash. Un compte peut avoir jusqu’à cinq clés actives et révoquer chacune d’elles immédiatement. Gardez les clés sur un serveur : une clé intégrée au code d’un navigateur ou d’une application peut être lue par n’importe qui.

Données de naissance

Les endpoints qui calculent un thème prennent un seul objet :

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

Endpoints

Le thème complet

POST /v1/chart/full renvoie tout le calcul sous la forme du fichier de démonstration publié, ce qui vous permet de comparer une réponse à un thème fixe avant d’écrire la moindre ligne de code. Réduit ici à deux corps, deux cuspides et les deux aspects les plus serrés :

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

Les endpoints de segment (planets, angles, houses, aspects, elements, fixed-stars) renvoient chacun une partie du même objet, pour les appelants qui n’ont besoin que de cette partie.

L’horoscope du jour

POST /v1/horoscope/daily est la moitié calculée d’un horoscope du jour : le ciel à midi UTC, la phase et le signe de la Lune, les événements célestes de la semaine à venir et, si vous envoyez birth, chaque transit sur ce thème avec son aspect, son orbe, s’il est appliquant ou séparant, le moment où il est ou a été exact, et la maison natale où se trouve le corps en transit. Les orbes de transit sont de 2° pour la Lune, le Soleil, Mercure, Vénus et Mars, et de 3° pour les corps plus lents. Deux champs relèvent de règles fixes et non de l’astronomie, et la réponse les énonce : tone (supportive pour le trigone et le sextile, challenging pour le carré et l’opposition, intensifying pour la conjonction) et focus, les trois contacts les mieux classés selon la vitesse de la planète et l’étroitesse de l’orbe. Il n’y a pas de texte rédigé ; cette partie vous revient.

Une réponse réelle pour le thème de démonstration le 2026-09-18, avec les listes réduites à deux éléments :

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

Endpoints API Pro

Six endpoints qui, ensemble, couvrent tout ce que calcule l’application. Chaque exemple ci-dessous est une réponse réelle pour le thème de démonstration, abrégée ; dans une requête, "..." remplace l’objet de données de naissance présenté plus haut.

Transits sur une période

POST /v1/transits prend birth, from et to (92 jours au plus) et renvoie, par date, chaque aspect exact de transit sur le thème natal, chaque entrée dans un signe et chaque station de la période, ainsi que les contacts actifs le premier jour avec leur phase et leur moment exact.

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

Synastrie

POST /v1/synastry prend personA et personB et renvoie les aspects de synastrie avec leurs orbes, les maisons de l’autre personne où tombent les planètes de chacune, et un score pour chacune des six sphères de vie. La seconde personne est ici fictive, elle aussi (1989-03-14, 07:45, New York).

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

Révolution solaire

POST /v1/solar-return prend birth, year et, en option, location, et renvoie le moment exact où le Soleil revient à sa longitude natale, avec le thème complet dressé pour cet instant. Il faut une heure de naissance : sans elle, le Soleil natal est incertain à un demi-degré près, ce qui décale la révolution d’environ douze heures.

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

Meilleurs jours pour une activité

POST /v1/timing prend birth, activity (general, business, romance, health, creative, travel, home ou clarity), from et to (62 jours au plus) et, en option, timezone, qui fixe le début de chaque jour. Chaque jour reçoit une note de 0 à 100 d’après la géométrie exacte des transits, pondérée selon les planètes qui comptent pour l’activité, et les cinq meilleurs jours viennent en premier. L’endpoint décrit le ciel ; il ne promet rien pour un jour donné.

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

Un lieu face à un thème

POST /v1/locations/score prend birth et location, avec des coordonnées. Le thème y est relocalisé, et la réponse donne les angles relocalisés, les planètes sur ces angles avec leurs orbes, un score de 0 à 10 pour chaque sphère de vie (5 est neutre) et l’intensité de la réaction du thème au lieu : forte quand une planète majeure se trouve à moins de 2° d’un angle, modérée à moins de 4°, faible sinon.

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

Les meilleures villes pour un thème

POST /v1/locations/rank prend birth, focus en option (au choix parmi identity, love, body, money, home, mind), region en option et limit, de 3 à 12, et classe un catalogue de 61 grandes villes. Toutes les villes de la Terre ne sont pas comparées ; tout autre lieu peut être noté avec l’endpoint ci-dessus.

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

Limites et tarifs

Les requêtes sont comptées par compte, toutes clés confondues, et le quota se renouvelle à 00:00 UTC. Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une requête rejetée comme invalide n’est pas comptée, un calcul qui échoue de notre côté est recrédité, et GET /v1/usage est toujours gratuit. API Pro est un abonnement distinct des formules de l’application : il n’inclut pas la formule Premium de l’application, et celle-ci ne l’inclut pas non plus. Les deux quotas sont également distincts : l’application compte les réponses de l’IA par semaine, cette API compte les calculs par jour UTC, et aucun des deux n’entame l’autre.

Erreurs

Toutes les erreurs ont la même structure : { "error": { "code", "message", "details"?, "docs" } }.

Paramètres de calcul

Ils sont fixes, et ce sont les paramètres de l’application elle-même, décrits en détail sur la page Vérifier votre thème et contrôlés par comparaison avec NASA JPL Horizons dans le rapport de précision. Fichiers de données Swiss Ephemeris, avec l’indicateur de vitesse activé. Zodiaque tropical, positions géocentriques et apparentes. Maisons Placidus. Nœud vrai. Lilith comme apogée lunaire osculateur. Part de Fortune calculée comme ASC + Lune − Soleil, pour les thèmes diurnes comme pour les thèmes nocturnes. Uniquement les cinq aspects majeurs : conjonction 8°, sextile 6°, carré 8°, trigone 8°, opposition 8°. Chaque aspect natal et de transit indique s’il est appliquant ou séparant, d’après les vitesses des deux corps, rétrogradation comprise.

Confidentialité

Les données de naissance sont des données personnelles. L’API les lit, calcule, répond et les oublie : aucun corps de requête n’est conservé, et rien de ce que vous envoyez ne sert à autre chose qu’à la réponse. Pour chaque requête, nous conservons l’endpoint, le code de statut et la latence. Consultez la politique de confidentialité.

Questions