Carta natal (occidental)

POST/api/v1/natal/calculate

Genera una carta natal occidental profesional con soporte para varios sistemas de casas, velocidades planetarias precisas, detección de estaciones, cuerpos adicionales (asteroides y nodos) y gestión explícita de nacimientos sin hora mediante time_known.

URL completa

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

Reintentos seguros con Idempotency-Key

Las solicitudes astrológicas POST autenticadas y facturables aceptan el encabezado opcional Idempotency-Key: <clave de operacion unica generada por el cliente>. Reutiliza la misma clave solo para reintentar exactamente el mismo method, path, query string y JSON body después de un timeout o error de red.

Una repetición completada devuelve la primera respuesta con Idempotency-Replayed: true, no vuelve a ejecutar el cálculo y no consume cuota adicional. Las claves se conservan durante unas 24 horas.

Reutilizar una clave con una solicitud modificada devuelve 409 idempotency_key_reused. Un duplicado mientras la primera solicitud sigue en curso devuelve 409 request_in_progress con Retry-After.

Parámetros del cuerpo de la solicitud

Parámetro	Type	Req	Description
name	string	No	Nombre del sujeto (para mostrar)
year	integer	Sí	Año de nacimiento (ex. 1990)
month	integer	Sí	Mes de nacimiento (1-12)
day	integer	Sí	Día de nacimiento (1-31)
time_known	boolean	No	Por defecto: true. Define false cuando se desconoce la hora de nacimiento. En este modo se omiten casas y ángulos, no se devuelven ubicaciones planetarias por casa y se reducen los metadatos de confianza.
hour	integer	No	Hora de nacimiento (0-23, formato 24 h). Requerida cuando time_known=true. Se ignora estructuralmente cuando time_known=false.
minute	integer	No	Minuto de nacimiento (0-59). Requerido cuando time_known=true. Se ignora estructuralmente cuando time_known=false.
city	string	Sí	Nombre de ciudad (usado para la búsqueda de coordenadas vía /geo/search)
lat	float	No	Latitud (-90 a 90). Opcional: se resuelve automáticamente desde city si falta
lng	float	No	Longitud (-180 a 180). Opcional: se resuelve automáticamente desde city si falta
tz_str	string	No	Zona horaria (ej. 'Europe/Paris' o 'AUTO'). Por defecto: AUTO
house_system	string	No	placidus (default), whole_sign, equal, koch, regiomontanus, porphyry, campanus
zodiac_type	string	No	tropical (por defecto) o sidereal. Sidereal usa el ayanamsa especificado.
fixed_stars	array[str]	No	Selector preferido para estrellas fijas. Acepta ids de packs como `royal_4` y `behenian_20`, nombres exactos como `Spica`, o `all` para el conjunto completo por defecto. Ejemplo: `["royal_4", "Spica"]`. .

Ejemplos de código

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "name": "John Doe",
    "year": 1990,
    "month": 5,
    "day": 15,
    "time_known": true,
    "hour": 14,
    "minute": 30,
    "city": "New York",
    "lat": 40.7128,
    "lng": -74.006,
    "tz_str": "AUTO",
    "house_system": "placidus",
    "zodiac_type": "tropical",
    "include_speed": true,
    "include_dignity": true,
    "include_minor_aspects": true,
    "include_stelliums": true,
    "fixed_stars": ["royal_4", "Spica"],
    "include_features": ["chiron", "lilith", "true_node"],
    "interpretation": {
        "enable": true,
        "style": "improved"
    },
    "orb_settings": {
        "Conjunction": 8.0,
        "Opposition": 8.0,
        "Trine": 8.0,
        "Square": 8.0,
        "Sextile": 6.0
    }
}'

Performance y optimización v2.2

Compression

Admitimos compresión Brotli (br) para máxima velocidad. Verifica que tu cliente envíe Accept-Encoding: br, gzip.

Cache

Las cartas natales son inmutables. Las respuestas incluyen Cache-Control: public, max-age=31536000, immutable. Puedes almacenar los resultados en caché indefinidamente para reducir llamadas API.

Datos de respuesta

{
  "subject": {
    "name": "John Doe",
    "city": "New York",
    "...": "...",
    "settings": {
      "house_system": "placidus",
      "julian_day": 2448032.27083,
      "delta_t_days": -0.0000339,
      "delta_t_seconds": -2.93,
      "zodiac_type": "Tropical",
      "time_known": true
    }
  },

  "planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Tau",
      "pos": 24.72,
      "abs_pos": 54.72,
      "house": 9,
      "retrograde": false,
      "speed": 0.96,
      "is_stationary": false
    },
    {
      "id": "moon",
      "name": "Moon",
      "sign": "Aqu",
      "pos": 14.23,
      "abs_pos": 314.23,
      "house": 5,
      "retrograde": false,
      "speed": 12.45,
      "is_stationary": false
    },
    {
      "id": "chiron",
      "name": "Chiron",
      "sign": "Can",
      "pos": 12.34,
      "abs_pos": 102.34,
      "house": 11,
      "retrograde": false,
      "speed": 0.05,
      "is_stationary": false
    }
    // Note: ASC is in "angles" object, not in "planets" array
  ],

  "houses": [
    { "house": 1, "name": "1", "sign": "Can", "sign_id": "cancer", "pos": 8.92, "abs_pos": 98.92 },
    { "house": 2, "name": "2", "sign": "Leo", "sign_id": "leo", "pos": 26.17, "abs_pos": 116.17 },
    // ... houses 3-11
    { "house": 12, "name": "12", "sign": "Gem", "sign_id": "gemini", "pos": 9.45, "abs_pos": 69.45 }
  ],

  "angles": {
    "asc": 98.92268897761204,   // Ascendant: absolute longitude (0-360°)
    "mc": 339.333397447316,    // Midheaven (MC)
    "ic": 159.333397447316,    // Imum Coeli (IC) - opposite MC
    "dc": 278.92268897761204,  // Descendant - opposite ASC
    "vertex": 235.34043201194  // Vertex point
  },

  "angles_details": {
    "asc": { "sign": "Can", "sign_id": "cancer", "pos": 8.92268897761204, "abs_pos": 98.92268897761204, "house": 1 },
    "mc": { "sign": "Pis", "sign_id": "pisces", "pos": 9.333397447316, "abs_pos": 339.333397447316, "house": 10 },
    "ic": { "sign": "Vir", "sign_id": "virgo", "pos": 9.333397447316, "abs_pos": 159.333397447316, "house": 4 },
    "dc": { "sign": "Cap", "sign_id": "capricorn", "pos": 8.92268897761204, "abs_pos": 278.92268897761204, "house": 7 },
    "vertex": { "sign": "Sco", "sign_id": "scorpio", "pos": 25.34043201194, "abs_pos": 235.34043201194, "house": 5 }
  },

  "aspects": [
    {
      "p1": "Sun",
      "p2": "Moon",
      "type": "Square",
      "orb": 5.51,
      "deg": 90.0,
      "is_major": true
    }
  ],

  "stelliums": {
    "threshold": 3,
    "signs": [
      { "sign_id": "taurus", "count": 3, "bodies": ["mercury", "sun", "venus"] }
    ],
    "houses": [],
    "total": 1
  },

  "fixed_stars": {
    "Regulus": {
      "id": "fixed_star_regulus",
      "name": "Regulus",
      "sign": "Leo",
      "sign_id": "leo",
      "pos": 29.7,
      "abs_pos": 149.7,
      "house": 2
    }
  },

  "confidence": {
    "houses": "high",
    "angles": "high",
    "overall": "high"
  },

  "interpretation": {
    "metadata": {
      "key_count": 57,
      "found_count": 57,
      "missing_keys": []
    },
    "sections": {
      "core_self": [
        {
          "id": "b86f87d3-2ea7-4dba-b1be-a667f4435584",
          "key": "planet.sun.sign.taurus",
          "category": "planet_sign",
          "title": "Sun in Taurus",
          "body": "Sun in Taurus emphasizes steadiness, material awareness, and a measured approach to life...",
          "tone": "improved",
          "tags": ["sun", "taurus"],
          "created_at": "2026-02-04T09:10:16.104443+00:00",
          "updated_at": "2026-02-04T09:10:16.104443+00:00"
        }
      ],
      "mind": [
        {
          "id": "fdea3513-56db-4349-b55e-87cb382ab520",
          "key": "planet.mercury.sign.taurus",
          "category": "planet_sign",
          "title": "Mercury in Taurus",
          "body": "Mercury in Taurus shapes a steady, deliberate mind...",
          "tone": "improved",
          "tags": ["mercury", "taurus"],
          "created_at": "2026-02-04T09:11:25.614751+00:00",
          "updated_at": "2026-02-04T09:11:25.614751+00:00"
        }
      ],
      "love_relating": [],
      "work_path": [],
      "social_collective": [],
      "karmic_healing": [
        {
          "id": "9ae37083-cadc-4a57-b3ac-7ec99645f0eb",
          "key": "planet.chiron.sign.cancer",
          "category": "planet_sign",
          "title": "Chiron in Cancer",
          "body": "Chiron in Cancer highlights a longstanding sensitivity around belonging...",
          "tone": "improved",
          "tags": ["chiron", "cancer"],
          "created_at": "2026-02-04T09:26:12.302848+00:00",
          "updated_at": "2026-02-04T09:26:12.302848+00:00"
        }
      ],
      "aspects": [
        {
          "p1": "moon",
          "p2": "sun",
          "type": "trine",
          "key": "aspect.moon.trine.sun",
          "title": "Sun Trine Moon",
          "content": "Sun trine Moon reflects an easy flow between instinct and intention..."
        }
      ]
    }
  }
}

Ejemplo de respuesta sin hora

{
  "subject": {
    "name": "Jane Doe",
    "settings": {
      "house_system": "placidus",
      "zodiac_type": "Tropical",
      "time_known": false
    }
  },
  "planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Sco",
      "sign_id": "scorpio",
      "pos": 10.84,
      "abs_pos": 220.84,
      "retrograde": false
    },
    {
      "id": "north_node",
      "name": "North Node",
      "sign": "Sag",
      "sign_id": "sagittarius",
      "pos": 2.18,
      "abs_pos": 242.18,
      "retrograde": true,
      "variant": "true"
    },
    {
      "id": "chiron",
      "name": "Chiron",
      "sign": "Leo",
      "sign_id": "leo",
      "pos": 14.02,
      "abs_pos": 134.02,
      "retrograde": false
    }
  ],
  "aspects": [
    {
      "p1": "moon",
      "p2": "sun",
      "type": "trine",
      "orb": 1.42,
      "deg": 120,
      "is_major": true
    }
  ],
  "confidence": {
    "houses": "unavailable",
    "angles": "unavailable",
    "overall": "medium"
  }
}

FAQ

¿Este endpoint proporciona una carta visual en SVG o PNG?

No. El endpoint Natal devuelve únicamente los datos calculados de la carta; no genera imágenes de carta en SVG ni PNG. Usa el endpoint Western Chart SVG cuando necesitas una carta visual.

¿Su API devuelve paralelos?

Sí. El endpoint Natal puede devolver paralelos y contraparalelos de declinación cuando los activas con"include_declination_aspects": true. No se devuelven por defecto.

{
  "include_declination_aspects": true,
  "declination_orb": 1.0
}

Los resultados se devuelven bajo declination_aspects y se resumen endeclination_aspects_summary. Los aspectos clásicos de longitud permanecen bajoaspects.

Endpoints relacionados

Transits

Comparer le ciel actuel a un carta natal

Carta vedique

Calculs sideraux (Lahiri)