Cartas Natales

Calculad cartas natales completas con posiciones planetarias, cúspides de casas y aspectos.

Cálculo Básico

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
datetime	string	Sí	Fecha y hora en formato ISO 8601
latitude	number	Sí	Latitud (-90 a 90)
longitude	number	Sí	Longitud (-180 a 180)
timezone	string	Sí	Identificador de zona horaria IANA
houseSystem	string	No	Sistema de casas (por defecto: "placidus")

Sistemas de Casas

• placidus — Placidus (por defecto)
• koch — Koch
• equal — Casas Iguales
• whole — Signo Completo
• campanus — Campanus
• regiomontanus — Regiomontanus
• porphyry — Porphyry

Respuesta

{
  "data": {
    "type": "natal-chart",
    "attributes": {
      "planets": {
        "sun": { "longitude": 84.5, "latitude": 0, "sign": "gemini", "house": 10 },
        "moon": { "longitude": 245.2, "latitude": -3.1, "sign": "sagittarius", "house": 4 }
      },
      "houses": {
        "1": { "cusp": 180.5, "sign": "libra" },
        "2": { "cusp": 210.3, "sign": "scorpio" }
      },
      "aspects": [
        { "planet1": "sun", "planet2": "moon", "aspect": "opposition", "orb": 0.7 }
      ]
    }
  }
}

Cuerpos Incluidos

Por defecto, se incluyen los siguientes cuerpos celestes:

• Sol, Luna
• Mercurio, Venus, Marte, Júpiter, Saturno, Urano, Neptuno, Plutón
• Nodo Norte, Nodo Sur
• Quirón, Lílith (Luna Negra)
• Parte de la Fortuna

Luna y Sol

Calculad la fase lunar, la iluminación, los horarios de salida/puesta y los datos de posición del Sol.

POST /api/calc/moon-sun

curl -X POST "https://api.astroapi.cloud/api/calc/moon-sun" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "2024-06-15T12:00",
    "location": {
      "latitude": 52.37,
      "longitude": 4.89,
      "timezone": "Europe/Amsterdam"
    }
  }'

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
dateTime	string	Sí	Fecha y hora en formato YYYY-MM-DDTHH:mm
location.latitude	number	Sí	Latitud (-90 a 90)
location.longitude	number	Sí	Longitud (-180 a 180)
location.timezone	string	Sí	Identificador de zona horaria IANA

Módulo Requerido

Este endpoint requiere el módulo module:moon.

Respuesta

{
  "data": {
    "moon": {
      "phaseName": "Waxing Gibbous",
      "phase": 0.62,
      "illumination": 0.78,
      "age": 9.2,
      "distance": 384400,
      "diameterDegrees": 0.52,
      "rise": "2024-06-15T14:23:00Z",
      "set": "2024-06-16T02:15:00Z"
    },
    "sun": {
      "rise": "2024-06-15T05:18:00Z",
      "set": "2024-06-15T22:03:00Z",
      "transit": "2024-06-15T13:40:00Z",
      "distance": 151820000,
      "diameterDegrees": 0.524,
      "twilight": {
        "civil": {
          "begin": "2024-06-15T04:38:00Z",
          "end": "2024-06-15T22:43:00Z"
        },
        "nautical": {
          "begin": "2024-06-15T03:32:00Z",
          "end": "2024-06-15T23:49:00Z"
        },
        "astronomical": {
          "begin": null,
          "end": null
        }
      }
    }
  }
}

Precisión de Cálculo

AstroAPI utiliza el Swiss Ephemeris para cálculos de alta precisión. Todas las posiciones se calculan con precisión de segundo de arco.

Beta: Motor de Cálculo Alternativo

Funcionalidad Experimental

Esta funcionalidad está en versión beta y puede tener problemas de precisión. Usadla con precaución en entornos de producción.

AstroAPI ofrece un motor de cálculo alternativo (calc2) que utiliza una implementación propia para leer y evaluar directamente los archivos de datos SE1 del Swiss Ephemeris, en lugar de usar la librería oficial del Swiss Ephemeris. Este motor está optimizado para velocidad y puede proporcionar tiempos de respuesta más rápidos.

Para usar el motor alternativo, incluid la cabecera X-Use-Calc2 en vuestra solicitud:

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "X-Use-Calc2: true" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

Diferencias Clave

Aspecto	Motor Estándar	Motor Calc2 (Beta)
Implementación	Swiss Ephemeris	Implementación propia
Fuente de Datos	Archivos efeméridos SE1	Archivos efeméridos SE1 (mismos datos)
Velocidad	Estándar	Potencialmente más rápido
Precisión	Precisión de segundo de arco (referencia)	Puede tener pequeñas desviaciones
Estado	Listo para producción	Beta

Cuándo Usar Calc2

• Recomendado para: Aplicaciones de alto volumen donde la velocidad tiene prioridad sobre la precisión absoluta
• No recomendado para: Aplicaciones que requieren máxima precisión astronómica

Limitaciones Conocidas

• La implementación propia puede producir resultados ligeramente diferentes en comparación con la librería oficial del Swiss Ephemeris
• Aún está en desarrollo activo y fase de pruebas
• Los resultados deben validarse con el motor estándar para aplicaciones críticas