Efemérides

POST/api/v1/ephemeris/calculate

Consulta posiciones planetarias para un timestamp único o un rango completo de fechas con pasos configurables, metadatos de nivel astrológico, aspectos opcionales y una salida table pensada para calendarios, exports y vistas de efemérides mes a mes.

URL completa

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

También hay un alias práctico GET /api/v1/ephemeris para flujos por query string.

Ejemplo de cuadrícula mensual

Es la forma más clara de entender lo que devuelve table_style=grid: una fila por día, una columna por cuerpo, con posiciones formateadas listas para un calendario front-end o una vista de export.

Fecha	Día	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

Elegir JSON

Usa format=json cuando quieres un instante único o una respuesta de rango fácil de procesar en tu lógica de aplicación.

Elegir Rows / Columns

Usa table_style=rows o columns cuando necesitas exports grandes, procesamiento tipo CSV o transformaciones UI personalizadas.

Elegir Grid

Usa table_style=grid cuando quieres una tabla mensual de efemérides con día de semana y tiempo sidéreo incluido.

Solicitudes más comunes

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"

Parámetros cles

Parámetro	Type	Req	Description
start	string	Sí	Fecha-hora ISO requerida. Si solo se proporciona start, el endpoint devuelve un único instante calculado para ese momento.
end	string	No	Fecha-hora ISO opcional para solicitudes por rango. Debe ser mayor o igual que start.
step	string	No	Intervalo entero en minutos, horas o días, como 1m, 5m, 15m, 1h, 6h, 1d o 7d. Por defecto: 1d.
city	string	No	Solo POST. Funciona como natal: si se proporciona sin lat/lng, el servidor resuelve automáticamente las coordenadas.
lat	float	No	Latitud. Si se proporcionan lat/lng, sustituyen la búsqueda de ciudad y se usan directamente.
lng	float	No	Longitud. Requerida con lat para solicitudes por coordenadas directas.
tz_str	string	No	Zona horaria o AUTO. AUTO usa las coordenadas resueltas y la fecha para determinar la zona.
bodies	array[str] \| csv	No	Cuerpos o puntos solicitados. Acepta un array POST o una cadena GET separada por comas.
format	string	No	json o table. Por defecto: json.
response_mode	string	No	Alias de format. Útil para solicitudes table en flujos por query string.
table_style	string	No	rows, columns o grid. Grid corresponde a la salida de calendario mensual.
zodiac_type	string	No	tropical (por defecto) o sidereal.
sidereal_ayanamsa	string	No	Se usa solo cuando zodiac_type=sidereal. Sigue las convenciones de nombres de natal.
house_system	string	No	Sistema de casas usado cuando se calculan casas o ángulos. Por defecto: placidus.
include_aspects	boolean	No	Si true, incluye datos de aspectos para cada instante calculado.
include_minor_aspects	boolean	No	Si true, amplía los aspectos para incluir tipos de aspectos menores.
include_moon_void_of_course	boolean	No	Si true, añade astrology.moon_void_of_course con el estado VOC actual, el próximo ingreso lunar y el próximo aspecto mayor aplicante de la Luna antes del ingreso cuando existe.
include_fixed_stars	boolean	No	Si true, devuelve el conjunto astrológico por defecto de estrellas fijas bajo fixed_stars para cada instante calculado.
fixed_stars	array[str] \| csv	No	Lista explícita opcional de estrellas fijas. Acepta un array POST o una cadena GET separada por comas, por ejemplo Spica,Regulus.
include_houses	boolean	No	Si true, devuelve las casas. Se activa automáticamente cuando hay coordenadas disponibles, salvo si se define explícitamente en false.
include_angles	boolean	No	Si true, devuelve el ascendente, el MC y datos de ángulos relacionados. Se activa automáticamente cuando hay coordenadas disponibles, salvo si se define explícitamente en false.

Comportamiento de localización

Flujo recomendado: usa City Search, deja que el usuario elija un resultado exacto y luego envía lat, lng e idealmente tz_str.
city en POST /api/v1/ephemeris/calculate es un fallback práctico. Si solo envías una ciudad, el servidor resuelve automáticamente las coordenadas.
Si ya tienes coordenadas, envíalas. No reenvíes solo el nombre de ciudad después de City Search salvo que quieras que el servidor haga una segunda búsqueda.
Cuando hay coordenadas, casas y ángulos se incluyen automáticamente salvo si los desactivas explícitamente.

Límites de rango

table_style=grid sirve para vistas mensuales y se limita a 31 filas. Las solicitudes más largas devuelven 400 grid_range_too_large.
Usa 1h y 1d para tablas y exports estándar.
Usa pasos en minutos como 1m o 5m solo para timing exacto.
Los rangos a nivel de minuto se limitan a 1440 filas, unas 24h a 1m. Las solicitudes más largas devuelven 400 minute_range_too_large.
rows y columns permiten exports más amplios, siempre sujetos al límite general de filas del endpoint.

Luna void of course

Define include_moon_void_of_course=true para añadir un objeto moon_void_of_course bajo astrology para cada instante calculado.
El cálculo usa los aspectos mayores exactos de la Luna con Sun, Mercury, Venus, Mars, Jupiter y Saturn antes de que la Luna cambie de signo.
Para respuestas table, el mismo objeto está disponible en cada payload raw_rows[].astrology.

Cuerpos admitidos

Cuerpos principales

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

Nodos y puntos lunares

Mean Node, True Node, Lilith, True Lilith

Asteroides y cuerpos menores

Chiron, Pholus, Ceres, Pallas, Juno, Vesta

Puntos calculados por coordenadas

Ascendant, MC, Vertex, Part of Fortune

Los puntos calculados por coordenadas requieren lat y lng.

Ejemplos de respuesta

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

Preguntas frecuentes sobre la API de efemérides de astrología occidental, tablas planetarias mensuales, datos de Luna void of course y opciones de cálculo admitidas.

¿Qué es una API de efemérides astrológicas?

Una API de efemérides astrológicas devuelve posiciones planetarias para una fecha y hora precisas, o para un rango de fechas. Este endpoint calcula posiciones tropicales o sidéreas de planetas, Luna, nodos, asteroides, ángulos, casas, aspectos, estrellas fijas y tablas mensuales de efemérides.

¿Puedo obtener una tabla mensual de efemérides planetarias?

Sí. Usa GET /api/v1/ephemeris con format=table y table_style=grid para recibir una fila por día y una columna por cuerpo solicitado. El modo grid está pensado para calendarios astrológicos mensuales y se limita a 31 filas por solicitud.

¿El endpoint de efemérides admite la Luna void of course?

Sí. Define include_moon_void_of_course=true para añadir astrology.moon_void_of_course a cada instante calculado. La respuesta indica si la Luna está void, el próximo ingreso lunar en un signo y, cuando existe, el próximo aspecto mayor aplicante de la Luna antes de ese ingreso.

¿Cuál es la precisión de las posiciones planetarias?

El servidor usa cálculos astronómicos precisos para longitud, latitud, velocidad, estado retrógrado, declinación, estrellas fijas y datos de casas cuando corresponde. Los resultados incluyen metadatos de día juliano para que las aplicaciones puedan auditar el contexto de cálculo.

¿Puedo solicitar efemérides tropicales y sidéreas?

Sí. Usa zodiac_type=tropical para efemérides occidentales tropicales por defecto, o zodiac_type=sidereal con sidereal_ayanamsa, por ejemplo lahiri, para cálculos sidéreos.

¿Puedo incluir casas y ángulos en una solicitud de efemérides?

Sí. Envía lat y lng, o una city resoluble en POST, y activa include_houses o include_angles. Cuando hay coordenadas, casas y ángulos se activan automáticamente salvo desactivación explícita.

¿Qué pasos de tiempo están admitidos?

El endpoint admite intervalos enteros en minutos, horas y días, como 1m, 5m, 15m, 1h, 6h, 1d y 7d. Los rangos a nivel de minuto se limitan a 1440 filas, mientras que las tablas grid se limitan a 31 filas.

¿Puedo calcular aspectos en la respuesta de efemérides?

Sí. Define include_aspects=true para incluir datos de aspectos en cada instante calculado. Define include_minor_aspects=true si también necesitas aspectos menores además de los aspectos mayores.

¿Qué planetas y puntos astrológicos puedo solicitar?

El endpoint admite 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 y Part of Fortune.

¿Puedo usar la API de efemérides para aplicaciones y calendarios astrológicos?

Sí. El formato JSON funciona bien para lógica de aplicación, mientras que las salidas table rows, columns y grid sirven para calendarios astrológicos, dashboards, exports y vistas mensuales de efemérides.