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

Estrellas fijas

Datos de posición de una estrella fija concreta, que se indica por su nombre, tomados del catálogo estándar de estrellas fijas. Tanto la astrología védica como la occidental usan un puñado de estrellas brillantes como referencia (Aldebaran, Regulus, Spica, Antares), y los propios nakshatras llevan el nombre de sus yogataras, las estrellas de unión que los definen. Este endpoint da las coordenadas eclípticas y ecuatoriales de una estrella, su velocidad de cambio y su brillo. Envía `name` como nombre tradicional (`Aldebaran`, `Regulus`) o como designación de Bayer (`alTau`, `alLeo`); la búsqueda no distingue mayúsculas y minúsculas ni tiene en cuenta los espacios, y una coma inicial obliga a usar la forma de Bayer. Añade `date_time`, `timezone_as_float` y las `keys` que quieras. Importante: pon `set_default_positions` como primera entrada de `keys`. Las claves se ejecutan en el orden en que las das, y todas las claves de posición dependen de los indicadores de cálculo que configura esa clave; sin ella, fallan. Solo `magnitude`, que sale directamente del catálogo, funciona por sí sola. Las posiciones son siderales. `latitude` y `longitude` se aceptan pero no se usan: la posición geocéntrica de una estrella fija no depende de dónde estés.

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

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
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.
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.
name	string	obligatorio	`AldebaranRohiniAlgolAntaresRegulusSiriusSpicaTrappist-1Galactic CenterGal. CenterGreat AttractorVirgo Cluster` Una estrella fija del catálogo estándar de estrellas fijas: un nombre tradicional (Aldebaran, Regulus, Spica) o una designación de Bayer (alTau, alLeo). La búsqueda no distingue mayúsculas y minúsculas ni tiene en cuenta los espacios. Antepón una coma para obligar a usar la forma de Bayer, p. ej., ',alTau'. Hay disponibles unos 735 nombres tradicionales y 1117 designaciones, incluidos puntos no estelares como Galactic Center. Un nombre no reconocido devuelve 400.
timezone_as_float	number (double)	obligatorio	Diferencia horaria del lugar con UTC, en horas y con decimales. Ejemplo: 5.5 para la India (UTC+05:30), -5 para Nueva York en invierno, 5.75 para Nepal. NO se contrasta con date_time: si los dos no coinciden, recibes una respuesta correcta para un momento equivocado, así que toma ambos valores de la misma fuente. Usa la diferencia vigente en esa fecha, no la de hoy: para un nacimiento en verano en un país con horario de verano, hace falta la diferencia de verano. 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 (10)

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
declination	date_time	La declinación de la estrella en `date_time`, su ángulo al norte o al sur del ecuador celeste, devuelta como `{degrees, minutes, seconds}`. La conversión toma el valor absoluto, así que el signo se pierde y una declinación sur no se distingue de una norte: si necesitas el hemisferio, tómalo de la posición de la estrella en el catálogo.
distance	date_time	La distancia de la estrella a la Tierra en `date_time`, un único número en unidades astronómicas redondeado a tres decimales.
ecliptic_speeds	date_time	Velocidad a la que cambian las coordenadas eclípticas de la estrella en `date_time`, como `{longitude_speed, latitude_speed, distance_speed}`: las dos primeras en grados por día y la última en unidades astronómicas por día. Los valores son muy pequeños, ya que el movimiento aparente de una estrella fija se debe a la precesión y al movimiento propio, no a un movimiento orbital.
equatorial_speeds	date_time	Velocidad a la que cambian las coordenadas ecuatoriales de la estrella en `date_time`, como `{right_ascension_speed, declination_speed, distance_speed}`: las dos primeras en grados por día y la última en unidades astronómicas por día.
latitude	date_time	La latitud eclíptica de la estrella en `date_time` (a qué distancia está al norte o al sur del plano de la eclíptica), como un único número de grados redondeado a tres decimales, negativo hacia el sur. Esto es lo que sitúa a una estrella fuera de la franja zodiacal y explica por qué algunas estrellas brillantes nunca forman una conjunción exacta con un planeta.
longitude	date_time	La longitud eclíptica sideral de la estrella en `date_time`: un único número de grados de 0 a 360, redondeado a tres decimales.
magnitude	—	La magnitud visual aparente de la estrella según el catálogo, un único número; cuanto menor, más brillante, así que Aldebaran se devuelve como 0.86. Es la única clave del endpoint que no necesita ni fecha ni una llamada previa a `set_default_positions`.
retrograde	date_time	Si la longitud eclíptica de la estrella está disminuyendo en `date_time`: un único booleano, true cuando `longitude_speed` es negativo. Para una estrella fija esto es en la práctica siempre false, porque la precesión la hace avanzar por el zodíaco sideral.
right_ascension	date_time	La ascensión recta de la estrella en `date_time`, su coordenada este-oeste sobre el ecuador celeste, devuelta como `{hours, minutes, seconds}` en lugar de en grados decimales.
set_default_positions	—	Un modificador, no un valor: establece posiciones geocéntricas aparentes con velocidades y, a diferencia de la clave del mismo nombre en /api/astro/celestial/, también activa el indicador SIDEREAL, así que el valor por defecto de este endpoint es sideral, no tropical. Devuelve null. Ponlo primero en `keys`: los modificadores solo se aplican a las claves enumeradas después de ellos.

Ejemplo de solicitud

curl -X POST https://api.occultapi.com/api/astro/star/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2026-09-01T06:00:00+05:30","timezone_as_float":5.5,"latitude":26.9124,"longitude":75.7873,"name":"Aldebaran","keys":["set_default_positions","magnitude"]}'

Respuesta

{
  "data": {
    "set_default_positions": null,
    "magnitude": 0.86
  },
  "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.