API de carta natal

URL base: https://api.natalchart.ai. Cada solicitud lleva una clave de API, cada respuesta está en JSON y cada longitud se da con cuatro decimales de grado antes de convertirse en un signo. La clave es gratis: inicia sesión con una cuenta de NatalChart.AI y crea una.

Inicio rápido

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

La respuesta, para el nacimiento de demostración que se usa en todo el sitio (1991-09-06, 18:30, Kiev). Se muestran cinco de los cuerpos:

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

Servidor MCP para asistentes de IA

Los mismos cálculos se ofrecen como servidor MCP en https://www.natalchart.ai/mcp, para Claude, ChatGPT, Cursor y VS Code. Usa la misma clave y gasta el mismo cupo diario, una solicitud por cada llamada a una herramienta. La configuración de cada cliente: Servidor MCP para asistentes de IA.

Autenticación

Envía la clave como Authorization: Bearer nc_live_... (también sirve el encabezado X-API-Key). La clave completa se muestra una sola vez, al crearla; nosotros solo guardamos su hash. Una cuenta puede tener hasta cinco claves activas y revocar cualquiera de ellas al instante. Guarda las claves en un servidor: una clave incluida en el código de un navegador o de una aplicación la puede leer cualquiera.

Datos de nacimiento

Los endpoints que calculan una carta reciben un objeto:

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

Endpoints

La carta completa

POST /v1/chart/full devuelve el cálculo completo con la estructura del archivo de demostración publicado, así que puedes comprobar una respuesta con una carta fija antes de escribir código. Aquí aparece recortado a dos cuerpos, dos cúspides y los dos aspectos más exactos:

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

Los endpoints de segmento (planets, angles, houses, aspects, elements, fixed-stars) devuelven cada uno una parte del mismo objeto, para quien solo necesite esa parte.

El horóscopo diario

POST /v1/horoscope/daily es la mitad calculada de un horóscopo diario: el cielo al mediodía UTC, la fase y el signo de la Luna, los eventos en el cielo de los próximos siete días y, cuando envías birth, cada tránsito sobre esa carta con su aspecto, su orbe, si es aplicativo o separativo, el momento en que es o fue exacto y la casa natal en la que está el cuerpo en tránsito. Los orbes de tránsito son de 2° para la Luna, el Sol, Mercurio, Venus y Marte, y de 3° para los cuerpos más lentos. Dos campos son reglas fijas y no astronomía, y la respuesta lo indica: tone (supportive para el trígono y el sextil, challenging para la cuadratura y la oposición, intensifying para la conjunción) y focus, los tres contactos mejor clasificados por velocidad del planeta y exactitud. No hay texto escrito; esa parte es tuya.

Una respuesta real para la carta de demostración el 2026-09-18, con las listas recortadas a dos elementos:

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

Endpoints de API Pro

Seis endpoints que, juntos, son todo lo que calcula la aplicación. Cada ejemplo de abajo es una respuesta real para la carta de demostración, recortada; "..." en una solicitud representa el objeto de datos de nacimiento que aparece arriba.

Tránsitos de un periodo

POST /v1/transits recibe birth, from y to (como máximo, 92 días) y devuelve, por fecha, cada aspecto exacto de tránsito sobre la carta natal, cada ingreso en un signo y cada estación del periodo, además de los contactos activos el primer día con su fase y el momento en que son exactos.

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

Sinastría

POST /v1/synastry recibe personA y personB y devuelve los aspectos entre las cartas con sus orbes, en qué casas de la otra persona caen los planetas de cada una y una puntuación para cada una de las seis esferas de la vida. Aquí la segunda persona también es ficticia (1989-03-14, 07:45, Nueva York).

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

Revolución solar

POST /v1/solar-return recibe birth, year y location (opcional), y devuelve el momento exacto en que el Sol vuelve a su longitud natal, con la carta completa levantada para ese momento. Necesita la hora de nacimiento: sin ella, el Sol natal tiene una incertidumbre de medio grado, lo que desplaza la revolución unas doce horas.

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

Mejores días para una actividad

POST /v1/timing recibe birth, activity (general, business, romance, health, creative, travel, home o clarity), from y to (como máximo, 62 días) y timezone (opcional), que marca el inicio de cada día. Cada día se puntúa de 0 a 100 a partir de la geometría exacta de los tránsitos, ponderada según los planetas que importan para la actividad, y los cinco mejores días van primero. Describe el cielo; no promete cómo será un día.

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

Un lugar frente a una carta

POST /v1/locations/score recibe birth y location con coordenadas. La carta se relocaliza allí, y la respuesta da los ángulos relocalizados, los planetas sobre ellos con sus orbes, una puntuación de 0 a 10 para cada esfera de la vida (5 es neutral) y la intensidad con la que la carta reacciona al lugar: fuerte cuando un planeta principal está a menos de 2° de un ángulo, moderada a menos de 4° y débil en los demás casos.

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

Las mejores ciudades para una carta

POST /v1/locations/rank recibe birth, focus (opcional, cualquiera de identity, love, body, money, home, mind), region (opcional) y limit, de 3 a 12, y ordena un catálogo de 61 grandes ciudades. No se comparan todas las ciudades de la Tierra; cualquier otro lugar se puede puntuar con el endpoint anterior.

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

Límites y precios

Las solicitudes se cuentan por cuenta, sumando todas sus claves, y el cupo se renueva a las 00:00 UTC. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una solicitud rechazada por no ser válida no se cuenta, un cálculo que falla por nuestra parte se devuelve al cupo y GET /v1/usage siempre es gratis. API Pro es una suscripción independiente de los planes de la aplicación: no incluye el plan Premium de la aplicación, y el plan Premium de la aplicación tampoco la incluye. Los dos cupos también son independientes: la aplicación cuenta las respuestas de IA por semana, esta API cuenta los cálculos por día UTC, y ninguno consume el otro.

Errores

Todos los errores tienen la misma estructura: { "error": { "code", "message", "details"?, "docs" } }.

Ajustes de cálculo

Son fijos y son los ajustes de la propia aplicación, descritos en detalle en la página Verifica tu carta y comprobados con JPL Horizons de la NASA en el informe de precisión. Archivos de datos de Swiss Ephemeris con el indicador de velocidad activado. Zodiaco tropical, posiciones geocéntricas y aparentes. Casas Placidus. Nodo lunar verdadero. Lilith como apogeo lunar osculador. Parte de la Fortuna como ASC + Luna − Sol, igual en las cartas diurnas y nocturnas. Solo los cinco aspectos mayores: conjunción 8°, sextil 6°, cuadratura 8°, trígono 8°, oposición 8°. Cada aspecto natal y de tránsito indica si es aplicativo o separativo, a partir de las velocidades de los dos cuerpos, incluido el movimiento retrógrado.

Privacidad

Los datos de nacimiento son datos personales. La API los lee, calcula, responde y los olvida: no se guarda ningún cuerpo de solicitud y nada de lo que envías se usa para otra cosa que no sea la respuesta. De cada solicitud guardamos el endpoint, el código de estado y la latencia. Consulta la política de privacidad.

Preguntas