Ephemerides

POST/api/v1/ephemeris/calculate

Interrogez les positions planetaires pour un timestamp unique ou une plage de dates complete avec des pas configurables, des metadonnees de niveau astrologue, des aspects optionnels et une sortie table concue pour les calendriers, exports et vues d'ephemerides mois par mois.

URL complete

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 reponse 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 personnalisees.

Choisir Grid

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

Requetes 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"

Parametres cles

Parametre	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 requetes sur plage. Doit etre superieure ou egale a start.
step	string	Non	Intervalle entier en minutes, heures ou jours, comme 1m, 5m, 15m, 1h, 6h, 1d ou 7d. Par defaut : 1d.
city	string	Non	POST uniquement. Fonctionne comme natal : si fourni sans lat/lng, le serveur resout automatiquement les coordonnees.
lat	float	Non	Latitude. Si lat/lng sont fournis, ils remplacent la recherche de ville et sont utilises directement.
lng	float	Non	Longitude. Requis avec lat pour les requetes par coordonnees directes.
tz_str	string	Non	Fuseau horaire ou AUTO. AUTO utilise les coordonnees resolues et la date pour determiner le fuseau.
bodies	array[str] \| csv	Non	Corps ou points demandes. Accepte un tableau POST ou une chaine GET separee par des virgules.
format	string	Non	json ou table. Par defaut : json.
response_mode	string	Non	Alias de format. Utile pour les requetes 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 defaut) ou sidereal.
sidereal_ayanamsa	string	Non	Utilise seulement lorsque zodiac_type=sidereal. Suit les conventions de nommage de natal.
house_system	string	Non	Systeme de maisons utilise lorsque les maisons ou les angles sont calcules. Par defaut : placidus.
include_aspects	boolean	Non	Si true, inclut les donnees 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'etoiles fixes astrologiques par defaut sous fixed_stars pour chaque instant calcule.
fixed_stars	array[str] \| csv	Non	Liste explicite optionnelle d'etoiles fixes. Accepte un tableau POST ou une chaine GET separee par des virgules, par exemple Spica,Regulus.
include_houses	boolean	Non	Si true, renvoie les maisons. Active automatiquement lorsque les coordonnees sont disponibles, sauf si explicitement defini sur false.
include_angles	boolean	Non	Si true, renvoie l'ascendant, le MC et les donnees d'angles liees. Active automatiquement lorsque les coordonnees sont disponibles, sauf si explicitement defini 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 coordonnees.
Si vous avez deja les coordonnees, 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 coordonnees sont presentes, les maisons et les angles sont inclus automatiquement sauf si vous les desactivez explicitement.

Limites de plage

table_style=grid sert aux affichages mensuels et est limite a 31 lignes. Les requetes 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 requetes 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 void of course

Definissez 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 reponses table, le meme 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 coordonnees

Ascendant, MC, Vertex, Part of Fortune

Les points calcules par coordonnees necessitent lat et lng.

Exemples de reponse

{
  "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'ephemerides d'astrologie occidentale, les tableaux planetaires mensuels, les donnees de Lune void of course et les options de calcul prises en charge.

Qu'est-ce qu'une API d'ephemerides astrologiques ?

Une API d'ephemerides astrologiques renvoie les positions planetaires pour une date et une heure precises, ou sur une plage de dates. Cet endpoint calcule les positions tropicales ou siderales des planetes, de la Lune, des noeuds, des asteroides, des angles, des maisons, des aspects, des etoiles fixes et des tableaux d'ephemerides au format mensuel.

Puis-je obtenir un tableau mensuel d'ephemerides planetaires ?

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

L'endpoint d'ephemerides prend-il en charge la Lune void of course ?

Oui. Definissez include_moon_void_of_course=true pour ajouter astrology.moon_void_of_course a chaque instant calcule. La reponse 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 precision des positions planetaires ?

Le serveur utilise des calculs astronomiques precis pour la longitude, la latitude, la vitesse, l'etat retrograde, la declinaison, les etoiles fixes et les donnees de maisons lorsque c'est applicable. Les resultats incluent les metadonnees de jour julien afin que les applications puissent auditer le contexte de calcul.

Puis-je demander des ephemerides tropicales et siderales ?

Oui. Utilisez zodiac_type=tropical pour les ephemerides occidentales tropicales par defaut, ou zodiac_type=sidereal avec sidereal_ayanamsa, par exemple lahiri, pour les calculs sideraux.

Puis-je inclure les maisons et les angles dans une requete d'ephemerides ?

Oui. Envoyez lat et lng, ou une city resolvable en POST, puis activez include_houses ou include_angles. Lorsque les coordonnees sont presentes, les maisons et les angles sont actives automatiquement sauf desactivation 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 reponse d'ephemerides ?

Oui. Definissez include_aspects=true pour inclure les donnees d'aspects pour chaque instant calcule. Definissez include_minor_aspects=true si vous avez aussi besoin des aspects mineurs en plus des aspects majeurs.

Quelles planetes 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'ephemerides 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'ephemerides mois par mois.