API Éphémérides | Documentation FreeAstroAPI

Éphémérides

POST/api/v1/ephemeris/calculate

Interrogez les positions planétaires pour un timestamp unique ou une plage de dates complète avec des pas configurables, des métadonnées de niveau astrologue, des aspects optionnels et une sortie table concue pour les calendriers, exports et vues d'éphémérides mois par mois.

URL complète

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

Un alias pratique GET /api/v1/ephemeris est aussi disponible pour les flux en query string.

Exemple de grille mensuelle

C'est la maniere la plus claire de comprendre ce que renvoie table_style=grid : une ligne par jour, une colonne par corps, avec des positions formatees pretes pour un calendrier front-end ou une vue d'export.

Date	Jour	Sid.t	Sun	Moon	Mercury	Venus	Mars	Jupiter	Saturn
1	Sun	10:35:16	10°24' Pis	09°07' Leo	21°58' Pis Rx	23°13' Pis	28°45' Aqu	15°15' Can Rx	01°43' Ari
2	Mon	10:39:12	11°25' Pis	22°53' Leo	21°28' Pis Rx	24°28' Pis	29°32' Aqu	15°13' Can Rx	01°51' Ari
3	Tue	10:43:09	12°25' Pis	06°25' Vir	20°50' Pis Rx	25°42' Pis	00°19' Pis	15°12' Can Rx	01°58' Ari
4	Wed	10:47:05	13°25' Pis	19°43' Vir	20°05' Pis Rx	26°57' Pis	01°06' Pis	15°10' Can Rx	02°05' Ari
5	Thu	10:51:02	14°25' Pis	02°44' Lib	19°15' Pis Rx	28°12' Pis	01°54' Pis	15°09' Can Rx	02°12' Ari
6	Fri	10:54:59	15°25' Pis	15°28' Lib	18°19' Pis Rx	29°27' Pis	02°41' Pis	15°08' Can Rx	02°20' Ari
7	Sat	10:58:55	16°25' Pis	27°56' Lib	17°20' Pis Rx	00°41' Ari	03°28' Pis	15°07' Can Rx	02°27' Ari
8	Sun	11:02:52	17°25' Pis	10°10' Sco	16°20' Pis Rx	01°56' Ari	04°16' Pis	15°06' Can Rx	02°34' Ari
9	Mon	11:06:48	18°25' Pis	22°14' Sco	15°19' Pis Rx	03°10' Ari	05°03' Pis	15°06' Can Rx	02°41' Ari
10	Tue	11:10:45	19°25' Pis	04°10' Sag	14°19' Pis Rx	04°25' Ari	05°50' Pis	15°05' Can Rx	02°49' Ari
11	Wed	11:14:41	20°25' Pis	16°03' Sag	13°22' Pis Rx	05°40' Ari	06°37' Pis	15°05' Can Rx	02°56' Ari
12	Thu	11:18:38	21°25' Pis	27°57' Sag	12°28' Pis Rx	06°54' Ari	07°25' Pis	15°05' Can	03°04' Ari
13	Fri	11:22:34	22°25' Pis	09°57' Cap	11°38' Pis Rx	08°09' Ari	08°12' Pis	15°06' Can	03°11' Ari
14	Sat	11:26:31	23°25' Pis	22°09' Cap	10°53' Pis Rx	09°23' Ari	08°59' Pis	15°06' Can	03°18' Ari
15	Sun	11:30:28	24°25' Pis	04°35' Aqu	10°14' Pis Rx	10°38' Ari	09°46' Pis	15°07' Can	03°26' Ari
16	Mon	11:34:24	25°24' Pis	17°19' Aqu	09°41' Pis Rx	11°52' Ari	10°34' Pis	15°08' Can	03°33' Ari
17	Tue	11:38:21	26°24' Pis	00°24' Pis	09°14' Pis Rx	13°06' Ari	11°21' Pis	15°09' Can	03°41' Ari
18	Wed	11:42:17	27°24' Pis	13°51' Pis	08°54' Pis Rx	14°21' Ari	12°08' Pis	15°10' Can	03°48' Ari
19	Thu	11:46:14	28°24' Pis	27°39' Pis	08°39' Pis Rx	15°35' Ari	12°55' Pis	15°11' Can	03°56' Ari
20	Fri	11:50:10	29°23' Pis	11°44' Ari	08°31' Pis Rx	16°49' Ari	13°42' Pis	15°13' Can	04°03' Ari
21	Sat	11:54:07	00°23' Ari	26°03' Ari	08°30' Pis	18°04' Ari	14°30' Pis	15°15' Can	04°10' Ari
22	Sun	11:58:03	01°23' Ari	10°30' Tau	08°34' Pis	19°18' Ari	15°17' Pis	15°17' Can	04°18' Ari
23	Mon	12:02:00	02°22' Ari	24°59' Tau	08°43' Pis	20°32' Ari	16°04' Pis	15°19' Can	04°25' Ari
24	Tue	12:05:57	03°22' Ari	09°26' Gem	08°58' Pis	21°46' Ari	16°51' Pis	15°21' Can	04°33' Ari
25	Wed	12:09:53	04°21' Ari	23°45' Gem	09°18' Pis	23°00' Ari	17°38' Pis	15°24' Can	04°40' Ari
26	Thu	12:13:50	05°21' Ari	07°55' Can	09°43' Pis	24°15' Ari	18°25' Pis	15°27' Can	04°48' Ari
27	Fri	12:17:46	06°20' Ari	21°52' Can	10°13' Pis	25°29' Ari	19°12' Pis	15°30' Can	04°55' Ari
28	Sat	12:21:43	07°19' Ari	05°36' Leo	10°47' Pis	26°43' Ari	19°59' Pis	15°33' Can	05°03' Ari
29	Sun	12:25:39	08°19' Ari	19°08' Leo	11°25' Pis	27°57' Ari	20°46' Pis	15°36' Can	05°10' Ari
30	Mon	12:29:36	09°18' Ari	02°27' Vir	12°07' Pis	29°11' Ari	21°33' Pis	15°39' Can	05°18' Ari
31	Tue	12:33:32	10°17' Ari	15°34' Vir	12°53' Pis	00°25' Tau	22°20' Pis	15°43' Can	05°25' Ari

Choisir JSON

Utilisez format=json lorsque vous voulez un instant unique ou une réponse de plage facile a traiter par votre logique applicative.

Choisir Rows / Columns

Utilisez table_style=rows ou columns lorsque vous avez besoin de grands exports, de traitements de type CSV ou de transformations UI personnalisées.

Choisir Grid

Utilisez table_style=grid lorsque vous voulez un tableau d'éphémérides mensuel avec jour de semaine et temps sideral inclus.

Requêtes les plus courantes

curl -X POST "https://api.freeastroapi.com/api/v1/ephemeris/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
   "start": "2026-03-01T00:00:00Z",
   "bodies": ["Sun", "Moon", "Mercury"],
   "include_moon_void_of_course": true,
   "fixed_stars": ["Spica", "Regulus"]
 }'

curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
 -H "x-api-key: YOUR_API_KEY" \
 --data-urlencode "start=2026-03-01T00:00:00Z" \
 --data-urlencode "end=2026-03-31T00:00:00Z" \
 --data-urlencode "step=1d" \
 --data-urlencode "response_mode=table" \
 --data-urlencode "table_style=grid" \
 --data-urlencode "bodies=Sun,Moon,Mercury,Venus,Mars,Jupiter,Saturn,Uranus,Neptune,Pluto,Chiron,True_Lilith"

curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
 -H "x-api-key: YOUR_API_KEY" \
 --data-urlencode "start=2026-03-14T04:00:00Z" \
 --data-urlencode "end=2026-03-14T08:00:00Z" \
 --data-urlencode "step=5m" \
 --data-urlencode "bodies=Moon,Sun"

Paramètres cles

Paramètre	Type	Req	Description
start	string	Oui	Date-heure ISO requise. Si seul start est fourni, l'endpoint renvoie un seul instant calcule pour ce moment.
end	string	Non	Date-heure ISO optionnelle pour les requêtes sur plage. Doit etre supérieure ou egale a start.
step	string	Non	Intervalle entier en minutes, heures ou jours, comme 1m, 5m, 15m, 1h, 6h, 1d ou 7d. Par défaut : 1d.
city	string	Non	POST uniquement. Fonctionne comme natal : si fourni sans lat/lng, le serveur resout automatiquement les coordonnées.
lat	float	Non	Latitude. Si lat/lng sont fournis, ils remplacent la recherche de ville et sont utilisés directement.
lng	float	Non	Longitude. Requis avec lat pour les requêtes par coordonnées directes.
tz_str	string	Non	Fuseau horaire ou AUTO. AUTO utilise les coordonnées résolues et la date pour determiner le fuseau.
bodies	array[str] \| csv	Non	Corps ou points demandes. Accepte un tableau POST ou une chaine GET séparée par des virgules.
format	string	Non	json ou table. Par défaut : json.
response_mode	string	Non	Alias de format. Utile pour les requêtes table dans des flux par query string.
table_style	string	Non	rows, columns ou grid. Grid correspond a la sortie de calendrier mensuel.
zodiac_type	string	Non	tropical (par défaut) ou sidereal.
sidereal_ayanamsa	string	Non	Utilise seulement lorsque zodiac_type=sidereal. Suit les conventions de nommage de natal.
house_system	string	Non	Système de maisons utilise lorsque les maisons ou les angles sont calcules. Par défaut : placidus.
include_aspects	boolean	Non	Si true, inclut les données d'aspects pour chaque instant calcule.
include_minor_aspects	boolean	Non	Si true, etend les aspects pour inclure les types d'aspects mineurs.
include_moon_void_of_course	boolean	Non	Si true, ajoute astrology.moon_void_of_course avec l'etat VOC actuel, le prochain ingress lunaire et le prochain aspect majeur appliquant de la Lune avant ingress lorsqu'il existe.
include_fixed_stars	boolean	Non	Si true, renvoie le jeu d'étoiles fixes astrologiques par défaut sous fixed_stars pour chaque instant calcule.
fixed_stars	array[str] \| csv	Non	Liste explicite optionnelle d'étoiles fixes. Accepte un tableau POST ou une chaine GET séparée par des virgules, par exemple Spica,Regulus.
include_houses	boolean	Non	Si true, renvoie les maisons. Active automatiquement lorsque les coordonnées sont disponibles, sauf si explicitement défini sur false.
include_angles	boolean	Non	Si true, renvoie l'ascendant, le MC et les données d'angles liees. Active automatiquement lorsque les coordonnées sont disponibles, sauf si explicitement défini sur false.

Comportement de localisation

Flux recommande : utilisez City Search, laissez l'utilisateur choisir un resultat exact, puis envoyez lat, lng et idealement tz_str.
city sur POST /api/v1/ephemeris/calculate est un fallback pratique. Si vous envoyez seulement une ville, le serveur resout automatiquement les coordonnées.
Si vous avez déjà les coordonnées, envoyez-les. Ne renvoyez pas seulement le nom de ville apres City Search sauf si vous voulez que le serveur fasse une seconde recherche.
Lorsque les coordonnées sont presentes, les maisons et les angles sont inclus automatiquement sauf si vous les désactivez explicitement.

Limites de plage

table_style=grid sert aux affichages mensuels et est limite a 31 lignes. Les requêtes plus longues renvoient 400 grid_range_too_large.
Utilisez 1h et 1d pour les tableaux et exports standards.
Utilisez des pas en minutes comme 1m ou 5m seulement pour le timing exact.
Les plages au niveau minute sont limitees a 1440 lignes, soit environ 24h a 1m. Les requêtes plus longues renvoient 400 minute_range_too_large.
rows et columns permettent des exports plus larges, toujours soumis a la limite generale de lignes de l'endpoint.

Lune hors cours

Définissez include_moon_void_of_course=true pour ajouter un objet moon_void_of_course sous astrology pour chaque instant calcule.
Le calcul utilise les aspects majeurs exacts de la Lune au Soleil, a Mercury, Venus, Mars, Jupiter et Saturn avant que la Lune change de signe.
Pour les réponses table, le même objet est disponible dans chaque payload raw_rows[].astrology.

Corps pris en charge

Corps principaux

Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto

Noeuds et points lunaires

Mean Node, True Node, Lilith, True Lilith

Asteroides et corps mineurs

Chiron, Pholus, Ceres, Pallas, Juno, Vesta

Points calcules par coordonnées

Ascendant, MC, Vertex, Part of Fortune

Les points calcules par coordonnées necessitent lat et lng.

Exemples de réponse

{
  "meta": {
    "start": "2026-03-01T00:00:00Z",
    "end": null,
    "step": null,
    "rows": 1,
    "bodies": ["Sun", "Moon", "Mercury"],
    "format": "json",
    "zodiac_type": "tropical",
    "sidereal_ayanamsa": null,
    "timezone": "UTC"
  },
  "data": {
    "timestamp": "2026-03-01T00:00:00Z",
    "local_timestamp": "2026-03-01T00:00:00+00:00",
    "subject": {
      "datetime": "2026-03-01T00:00:00+00:00",
      "location": {
        "city": null,
        "lat": null,
        "lng": null,
        "timezone": "UTC"
      },
      "settings": {
        "julian_day": 2461100.5,
        "julian_day_tt": 2461100.5007972275,
        "delta_t_days": 0.0007972275448330983,
        "delta_t_seconds": 68.8804598735797,
        "zodiac_type": "Tropical",
        "house_system": "placidus"
      }
    },
    "bodies": {
      "Sun": {
        "id": "sun",
        "name": "Sun",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "sign_id": "pisces",
        "pos": 10.406,
        "abs_pos": 340.406,
        "retrograde": false,
        "speed": 1.0037,
        "is_stationary": false,
        "latitude_deg": 0.000076,
        "distance_au": 0.990714622,
        "position_text": "10°24' Pisces",
        "degree_in_sign": 10.406,
        "longitude_deg": 340.406,
        "motion_state": "direct"
      },
      "Moon": {
        "id": "moon",
        "name": "Moon",
        "sign": "Leo",
        "sign_abbr": "Leo",
        "sign_id": "leo",
        "pos": 9.117,
        "abs_pos": 129.117,
        "retrograde": false,
        "speed": 13.8619,
        "is_stationary": false,
        "latitude_deg": 2.635536,
        "distance_au": 0.002504401,
        "position_text": "09°07' Leo",
        "degree_in_sign": 9.117,
        "longitude_deg": 129.117,
        "declination_deg": 20.516062,
        "motion_state": "direct"
      },
      "Mercury": {
        "id": "mercury",
        "name": "Mercury",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "sign_id": "pisces",
        "pos": 21.973,
        "abs_pos": 351.973,
        "retrograde": true,
        "speed": -0.428,
        "is_stationary": false,
        "latitude_deg": 3.294498,
        "distance_au": 0.70680082,
        "position_text": "21°58' Pisces Rx",
        "degree_in_sign": 21.973,
        "longitude_deg": 351.973,
        "declination_deg": -0.156033,
        "motion_state": "retrograde"
      }
    },
    "astrology": {
      "retrograde_bodies": ["Mercury"],
      "stations": [],
      "ingresses": [
        {
          "body": "Moon",
          "sign": "Leo",
          "degree_in_sign": 9.117,
          "direction": "entering_sign"
        }
      ],
      "angular_bodies": [],
      "notable_conditions": [
        "retrograde:Mercury",
        "ingress:Moon",
        "moon_phase:waxing_gibbous"
      ],
      "moon_phase": {
        "name": "Waxing Gibbous",
        "phase_angle_deg": 148.711,
        "is_waxing": true
      },
      "moon_void_of_course": {
        "is_void": false,
        "definition": "No further exact major Moon aspect to Sun, Mercury, Venus, Mars, Jupiter, or Saturn before the Moon changes sign.",
        "current_sign": "Leo",
        "next_sign": "Virgo",
        "sign_ingress_at": "2026-03-02T12:33:41Z",
        "next_applying_aspect": {
          "body": "mars",
          "aspect": "opposition",
          "exact_at": "2026-03-02T12:27:23Z"
        }
      }
    }
  }
}

{
  "meta": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T00:00:00Z",
    "step": "1d",
    "rows": 31,
    "bodies": ["Sun", "Moon", "Mercury"],
    "format": "table",
    "table_style": "grid",
    "zodiac_type": "tropical",
    "sidereal_ayanamsa": null,
    "timezone": "UTC"
  },
  "display": {
    "sign_style": "abbr",
    "cell_format": "parts",
    "motion_markers": {
      "retrograde": "Rx",
      "stationary": "S"
    },
    "columns": ["date", "weekday", "sidereal_time", "Sun", "Moon", "Mercury"]
  },
  "rows": [
    {
      "date": { "iso": "2026-03-01", "day": 1 },
      "weekday": "Sun",
      "sidereal_time": "10:35:16",
      "Sun": {
        "text": "10°24' Pis",
        "degree_text": "10°24'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": null,
        "entered_sign": false,
        "station": false
      },
      "Mercury": {
        "text": "21°58' Pis Rx",
        "degree_text": "21°58'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": "Rx",
        "entered_sign": false,
        "station": false
      }
    },
    {
      "date": { "iso": "2026-03-02", "day": 2 },
      "weekday": "Mon",
      "sidereal_time": "10:39:12",
      "Sun": {
        "text": "11°25' Pis",
        "degree_text": "11°25'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": null,
        "entered_sign": false,
        "station": false
      },
      "Moon": {
        "text": "22°53' Leo",
        "degree_text": "22°53'",
        "sign": "Leo",
        "sign_abbr": "Leo",
        "motion_marker": null,
        "entered_sign": true,
        "station": false
      },
      "Mercury": {
        "text": "21°28' Pis Rx",
        "degree_text": "21°28'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": "Rx",
        "entered_sign": false,
        "station": false
      }
    }
  ],
  "raw_rows": [
    {
      "timestamp": "2026-03-01T00:00:00Z",
      "bodies": {
        "Sun": {
          "abs_pos": 340.406,
          "degree_in_sign": 10.406,
          "declination_deg": -7.665505,
          "speed": 1.0037
        },
        "Moon": {
          "abs_pos": 129.117,
          "degree_in_sign": 9.117,
          "declination_deg": 20.516062,
          "speed": 13.8619
        },
        "Mercury": {
          "abs_pos": 351.973,
          "degree_in_sign": 21.973,
          "declination_deg": -0.156033,
          "speed": -0.428
        }
      }
    }
  ]
}

FAQ

Questions frequentes sur l'API d'éphémérides d'astrologie occidentale, les tableaux planétaires mensuels, les données de Lune hors cours et les options de calcul prises en charge.

Qu'est-ce qu'une API d'éphémérides astrologiques ?

Une API d'éphémérides astrologiques renvoie les positions planétaires pour une date et une heure précisés, ou sur une plage de dates. Cet endpoint calcule les positions tropicales ou siderales des planètes, de la Lune, des noeuds, des asteroides, des angles, des maisons, des aspects, des étoiles fixes et des tableaux d'éphémérides au format mensuel.

Puis-je obtenir un tableau mensuel d'éphémérides planétaires ?

Oui. Utilisez GET /api/v1/ephemeris avec format=table et table_style=grid pour recevoir une ligne par jour et une colonne par corps demande. Le mode grille est concu pour les calendriers astrologiques mensuels et limite a 31 lignes par requête.

L'endpoint d'éphémérides prend-il en charge la Lune hors cours ?

Oui. Définissez include_moon_void_of_course=true pour ajouter astrology.moon_void_of_course a chaque instant calcule. La réponse indique si la Lune est void, le prochain ingress de la Lune dans un signe et, lorsqu'il existe, le prochain aspect majeur appliquant de la Lune avant cet ingress.

Quelle est la précision des positions planétaires ?

Le serveur utilise des calculs astronomiques précis pour la longitude, la latitude, la vitesse, l'etat rétrograde, la déclinaison, les étoiles fixes et les données de maisons lorsque c'est applicable. Les resultats incluent les métadonnées de jour julien afin que les applications puissent auditer le contexte de calcul.

Puis-je demander des éphémérides tropicales et siderales ?

Oui. Utilisez zodiac_type=tropical pour les éphémérides occidentales tropicales par défaut, ou zodiac_type=sidereal avec sidereal_ayanamsa, par exemple lahiri, pour les calculs sideraux.

Puis-je inclure les maisons et les angles dans une requête d'éphémérides ?

Oui. Envoyez lat et lng, ou une city resolvable en POST, puis activez include_houses ou include_angles. Lorsque les coordonnées sont presentes, les maisons et les angles sont activés automatiquement sauf désactivation explicite.

Quels pas de temps sont pris en charge ?

L'endpoint prend en charge des intervalles entiers en minutes, heures et jours, comme 1m, 5m, 15m, 1h, 6h, 1d et 7d. Les plages au niveau minute sont limitees a 1440 lignes, tandis que les tableaux en grille sont limites a 31 lignes.

Puis-je calculer les aspects dans la réponse d'éphémérides ?

Oui. Définissez include_aspects=true pour inclure les données d'aspects pour chaque instant calcule. Définissez include_minor_aspects=true si vous avez aussi besoin des aspects mineurs en plus des aspects majeurs.

Quelles planètes et quels points astrologiques puis-je demander ?

L'endpoint prend en charge Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, Mean Node, True Node, Lilith, True Lilith, Ascendant, MC, Vertex et Part of Fortune.

Puis-je utiliser l'API d'éphémérides pour des applications et calendriers astrologiques ?

Oui. Le format JSON convient a la logique applicative, tandis que les sorties table rows, columns et grid conviennent aux calendriers astrologiques, tableaux de bord, exports et affichages d'éphémérides mois par mois.