POST/api/astro/celestial/1 crédito

Posiciones celestes

Efemérides en bruto para uno o más cuerpos: dónde está un planeta, a qué velocidad se mueve, cuándo sale y se pone, si está retrógrado. Es la capa astronómica sobre la que se apoya el resto de la API, expuesta directamente, y llega mucho más allá de los nueve grahas védicos: se pueden consultar los planetas exteriores, Quirón y los asteroides, los puntos ficticios uranianos y varias lunas planetarias. Hay dos tipos de claves. Las claves `set_*` son modificadores: cambian cómo se calculan las posiciones o las horas de salida y puesta (geocéntricas, topocéntricas o heliocéntricas, aparentes o verdaderas, con o sin nutación, siderales o tropicales, salida hindú o salida por el centro del disco), y cada una devuelve null. Las claves `get_*`, junto con `rise_time`, `set_time`, `is_retrograde` e `is_stationary`, devuelven valores. Como las claves se ejecutan en el orden en que las enumeras, un modificador solo afecta a las claves de valor que aparecen después de él en el array. `planet_names` recibe una lista de nombres en mayúsculas y la respuesta se indexa por ellos, así que una llamada para MARS devuelve `{"data": {"MARS": {"get_longitude": 123.45}}}`. Un nombre que no se reconoce no hace fallar la solicitud: esa entrada devuelve `{"error": "Unknown planet '<name>'"}`. Ten en cuenta que aquí los nodos se llaman MEAN_NODE y TRUE_NODE, no 'northtruenode', como en /api/astro/chart/.

https://api.occultapi.com/api/astro/celestial/

Probar solicitud

Autenticación

Envía tu clave en la cabecera X-API-Key. La clave es una credencial de servidor: nunca la pongas en el JavaScript del navegador ni en una app móvil.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Campos de la solicitud

Campo	Tipo	Obligatorio	Notas
altitude	number (double)	obligatorio
date_time	string (date-time)	obligatorio	El momento del cálculo, en ISO 8601. Incluye SIEMPRE la diferencia con UTC o una Z final: un valor sin zona horaria se interpreta como Asia/Kolkata (UTC+05:30), no como UTC, y puede devolver con un 200 el resultado del día anterior. '2026-09-01T06:00:00Z' y '2026-09-01 06:00:00' son instantes distintos y dan respuestas distintas. Restricción de FORMATO, no un enum. DRF DateTimeField: solo ISO-8601 (formatos de entrada por defecto de DRF), p. ej., "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" o "2026-09-01 06:00:00" (sin zona horaria = se toma como UTC).
keys	array	obligatorio	Los cálculos que quieres recibir, como lista de nombres. Consulta la tabla de claves de este endpoint; un nombre que no se reconoce invalida toda la solicitud. Cada llamada cuesta un crédito, pidas las claves que pidas, así que pide todo lo que necesites de una vez en lugar de hacer varias llamadas. `set_default_risingset_hindu_risingset_disc_center_refractionset_disc_bottom_refractionset_disc_center_no_refractionset_disc_bottom_no_refractionset_default_positionsset_true_positionsset_topocentric_positionsset_heliocentric_positionsset_barycentric_positionsset_astrometric_positions` Array de cadenas. Las claves `set_` modifican los indicadores de cálculo del objeto Celestial; las claves `get_` / `rise_time` / `set_time` / `is_*` devuelven valores.
planet_names	array	obligatorio	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` Array de cadenas, longitud mínima 1. Ten en cuenta que aquí los nodos se llaman 'MEAN_NODE'/'TRUE_NODE', no al estilo 'northtruenode' de la salida de la carta. Un nombre que no se reconoce no hace fallar la solicitud: esa entrada devuelve {"error": "Unknown planet '<X>'"}.
time_zone	number (double)	obligatorio	min -12 · max 14
latitude	number (double)	opcional	Latitud del lugar, en grados decimales. Los valores positivos indican el norte y los negativos, el sur. Ejemplo: 26.9124 para Jaipur, 40.7128 para Nueva York. No se aceptan minutos ni segundos: conviértelos antes. min -89.9 · max 89.9
longitude	number (double)	opcional	Longitud del lugar, en grados decimales. Los valores positivos indican el este y los negativos, el oeste. Ejemplo: 75.7873 para Jaipur, -74.0060 para Nueva York. Cuidado con el signo: si falta el menos, Nueva York acaba en China. min -180 · max 180

Claves disponibles (31)

Indica en keys exactamente los cálculos que quieres. Si una clave no existe, se rechaza toda la solicitud. Pidas las que pidas, se cobra 1 crédito, así que agrúpalas en una sola llamada.

Clave	Campos adicionales	Descripción
get_altitude	date_time, latitude, longitude, altitude	Altura del cuerpo sobre el horizonte, en grados con seis decimales; un valor negativo indica que está por debajo. Requiere `latitude`, `longitude` y `altitude` en metros.
get_apsis	date_time	El próximo afelio y el próximo perihelio, los puntos de la órbita más lejano y más cercano al Sol. Devuelve un objeto `{Aphelion, Perihelion}` con un datetime UTC para cada uno, buscando hacia delante desde el momento indicado. Disponible solo para los cuerpos que cubre el modelo.
get_azimuth	date_time, latitude, longitude, altitude	Hacia dónde mirar a lo largo del horizonte para ver el cuerpo, en grados en sentido horario desde el norte, como un único número con seis decimales. Requiere `latitude`, `longitude` y `altitude`, y tiene en cuenta la refracción salvo que antes se haya activado un modificador sin refracción.
get_declination	date_time	Declinación, la distancia angular del cuerpo al norte o al sur del ecuador celeste, como objeto con `degrees`, `minutes` y `seconds`.
get_distance	date_time	Distancia al observador en unidades astronómicas, redondeada a tres decimales. Un único número; para la Luna es una pequeña fracción de una AU.
get_ecliptic_speeds	date_time	Velocidad del cuerpo, como objeto con `longitude_speed` y `latitude_speed` en grados por día y `distance_speed` en AU por día, todos con seis decimales. Una velocidad en longitud negativa indica que está retrógrado.
get_equatorial_speeds	date_time	Movimiento en coordenadas ecuatoriales: un objeto con `right_ascension_speed` y `declination_speed` en grados por día y `distance_speed` en AU por día, todos con seis decimales.
get_illumination	date_time	La magnitud visual aparente del cuerpo en ese momento, como un único número con seis decimales: cuanto menor y más negativa, más brillante. Disponible solo para los cuerpos que cubre el modelo de iluminación; los demás provocan un error.
get_latitude	date_time	Latitud eclíptica en grados con tres decimales: cuánto se aleja el cuerpo por encima o por debajo del plano de la eclíptica. Un único número, negativo hacia el sur.
get_longitude	date_time	Longitud eclíptica en grados, de 0 a 360, redondeada a tres decimales: un único número. Que sea tropical o sideral depende del modo de posición que esté activo.
get_right_ascension	date_time	Ascensión recta, el equivalente ecuatorial de la longitud, como objeto con `hours`, `minutes` y `seconds` en lugar de en grados decimales.
is_retrograde	date_time	True cuando la velocidad en longitud del cuerpo es negativa, es decir, cuando parece moverse hacia atrás por el zodíaco. Un único booleano.
is_stationary	date_time	Una comprobación aproximada de estación: true cuando la parte fraccionaria de la velocidad diaria en longitud del cuerpo se redondea a cero con tres decimales. Devuelve un booleano y, por cómo se comprueba, es un indicio, no una estación exacta.
rise_time	date_time, geopos	La salida del cuerpo, buscada a partir de la medianoche local (según la diferencia horaria de `time_zone`) de la fecha indicada en el lugar. Devuelve una lista de dos elementos: el momento de la salida como datetime en la hora local que corresponde a `time_zone` y, después, las cifras del día juliano en bruto. Qué definición de «salida» se aplica depende del modificador de salida o de disco que la preceda en el array de claves. Si el cuerpo no sale ni se pone dentro del intervalo de búsqueda (la luna en latitudes altas o el sol durante un día polar), la búsqueda subyacente falla y esto devuelve "2000-11-24T12:00:00Z", que es el día juliano cero y no un instante real. Trata ese valor exacto como ausencia de resultado. /api/astro/sunrise/ y /api/astro/moonrise/ devuelven null en el mismo caso.
set_astrometric_j_positions	—	Cambia a posiciones astrométricas referidas al equinoccio medio de J2000, con la nutación, la aberración y la deflexión de la luz desactivadas. Devuelve null.
set_astrometric_positions	—	Cambia a posiciones astrométricas: se corrige el tiempo de luz, pero no la aberración anual ni la deflexión gravitacional de la luz. Devuelve null.
set_barycentric_positions	—	Cambia a posiciones baricéntricas, referidas al baricentro del sistema solar. Devuelve null y solo funciona para cuerpos físicos, no para los nodos ni los apogeos.
set_default_positions	—	Un modificador, no un valor: activa las posiciones geocéntricas aparentes con velocidades, que en este endpoint son el valor por defecto TROPICAL. Devuelve null. Los modificadores `set_*` solo se aplican a las claves que aparecen después de ellos en `keys`, así que el orden importa: ponlo primero, o detrás de otro modificador para volver al valor por defecto. Ten en cuenta que la clave del mismo nombre en /api/astro/star/ activa, en cambio, posiciones SIDERALES.
set_default_rising	—	Restaura la definición por defecto de salida y puesta para `rise_time` y `set_time`. Es un modificador, no un valor: devuelve null y solo afecta a las claves que aparecen después de él.
set_disc_bottom_no_refraction	—	Calcula la salida y la puesta desde el borde inferior del disco, con la refracción desactivada. Devuelve null.
set_disc_bottom_refraction	—	Calcula la salida y la puesta desde el borde inferior del disco, aplicando la refracción atmosférica. Devuelve null.
set_disc_center_no_refraction	—	Calcula la salida y la puesta desde el centro del disco, con la refracción desactivada: geométricas, no observadas. Devuelve null y hace que cualquier `get_azimuth` y `get_altitude` posterior se calcule sin atmósfera.
set_disc_center_refraction	—	Calcula la salida y la puesta desde el centro del disco, aplicando la refracción atmosférica. Devuelve null y además hace que cualquier `get_azimuth` y `get_altitude` posterior use posiciones refractadas.
set_heliocentric_positions	—	Cambia a posiciones heliocéntricas, referidas al centro del Sol. Devuelve null. En este modo, el Sol, los nodos lunares y los apogeos lunares se devuelven como cero.
set_hindu_rising	—	Cambia las horas de salida y puesta a la convención hindú. Devuelve null; afecta a las claves `rise_time` y `set_time` que aparecen después en el array.
set_jpl_horizons_positions	—	Cambia a posiciones aparentes calculadas como lo hace JPL Horizons, para contrastarlas con ese servicio. Devuelve null.
set_mean_equinox_positions	—	Cambia a posiciones referidas al equinoccio medio de la fecha, desactivando la nutación. Devuelve null.
set_sidereal_positions	—	Cambia a posiciones siderales, es decir, la longitud tropical menos el ayanamsa. Devuelve null. El ayanamsa en sí se configura en otro lugar, así que se aplica el modo sideral vigente.
set_time	date_time, geopos	La puesta del cuerpo, buscada a partir de la medianoche local (según la diferencia horaria de `time_zone`) de la fecha indicada en el lugar. Tiene la misma estructura que `rise_time`: [datetime local, cifras del día juliano en bruto]. Pese al prefijo `set_`, devuelve un valor; no es uno de los modificadores. Si el cuerpo no sale ni se pone dentro del intervalo de búsqueda (la luna en latitudes altas o el sol durante un día polar), la búsqueda subyacente falla y esto devuelve "2000-11-24T12:00:00Z", que es el día juliano cero y no un instante real. Trata ese valor exacto como ausencia de resultado. /api/astro/sunrise/ y /api/astro/moonrise/ devuelven null en el mismo caso.
set_topocentric_positions	latitude, longitude, altitude	Cambia a posiciones topocéntricas, referidas al lugar del propio observador y no al centro de la Tierra. Requiere `latitude`, `longitude` y `altitude` en metros; devuelve null. La diferencia solo es apreciable en la Luna.
set_true_positions	—	Cambia a posiciones geométricas verdaderas, sin tener en cuenta el tiempo de luz: dónde está realmente el cuerpo, no dónde parece estar. Devuelve null.

Ejemplo de solicitud

curl -X POST https://api.occultapi.com/api/astro/celestial/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2024-11-20T08:40:08.658Z","keys":["set_default_positions","set_hindu_rising"],"latitude":26.9124,"longitude":75.7873,"time_zone":5.5,"altitude":0,"planet_names":["SUN"]}'

Respuesta

{
  "data": {
    "SUN": {
      "set_default_positions": null,
      "set_hindu_rising": null
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Obtenida de una llamada real con la solicitud de arriba, tal cual. Los resultados van dentro de data, cada uno bajo la clave que pediste.

Errores

Los errores de control de uso devuelven { "error": "…", "message": "<code>", "is_error": true }. Muestra error al usuario y usa message para decidir qué hace tu código. Consulta la referencia de errores.