Natal Chart API

Base URL: https://api.natalchart.ai. Every request carries an API key, every response is JSON, and every longitude is given to four decimals of a degree before it is turned into a sign. The key is free: sign in with a NatalChart.AI account and create one.

Quick start

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}}'

The response, for the demonstration birth used across this site (1991-09-06, 18:30, Kyiv). Five of the bodies are shown:

{
  "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"
  ]
}

Authentication

Send the key as Authorization: Bearer nc_live_... (an X-API-Key header works too). The full key is shown once, when you create it; we keep only its hash. An account holds up to five active keys and can revoke any of them at once. Keep keys on a server: a key shipped in browser or app code can be read by anyone.

Birth data

Endpoints that compute a chart take one object:

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

Endpoints

The full chart

POST /v1/chart/full returns the whole calculation in the shape of the published demonstration file, so you can check a response against a fixed chart before you write any code. Shortened here to two bodies, two cusps and the two tightest aspects:

{
  "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
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

The segment endpoints (planets, angles, houses, aspects, elements, fixed-stars) return one part of the same object each, for callers that need only that part.

The daily horoscope

POST /v1/horoscope/daily is the calculated half of a daily horoscope: the sky at noon UTC, the Moon’s phase and sign, the sky events of the coming week and, when you send birth, every transit to that chart with its aspect, its orb and the natal house the transiting body is in. Transit orbs are 2° for the Moon, Sun, Mercury, Venus and Mars and 3° for the slower bodies. Two fields are fixed rules rather than astronomy, and the response states them: tone (trine and sextile supportive, square and opposition challenging, conjunction intensifying) and focus, the three contacts that rank highest by planet speed and tightness. There is no written text; that part is yours.

API Pro endpoints

POST /v1/transits takes birth, from and to (at most 92 days) and returns every exact transit-to-natal aspect by date, every sign ingress and every station in the window. POST /v1/synastry takes personA and personB and returns the inter-chart aspects with orbs, the house overlays both ways and a score for each of six life spheres. POST /v1/solar-return takes birth, year and an optional location and returns the exact moment of the return with the full chart cast for it.

Limits and pricing

Requests are counted per account, across all of its keys, and the pool refills at 00:00 UTC. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A request rejected as invalid is not counted, a calculation that fails on our side is given back, and GET /v1/usage is always free. API Pro is a separate subscription from the app plans: it does not include app Premium, and app Premium does not include it.

Errors

Every error has one shape: { "error": { "code", "message", "details"?, "docs" } }.

Calculation settings

These are fixed, and they are the settings of the app itself, described in full on the verification page. Swiss Ephemeris data files with the speed flag on. Tropical zodiac, geocentric, apparent positions. Placidus houses. True lunar node. Lilith as the osculating lunar apogee. Part of Fortune as ASC + Moon − Sun for day and night charts alike. The five major aspects only: conjunction 8°, sextile 6°, square 8°, trine 8°, opposition 8°. Applying and separating are not labelled; the transits endpoint gives the exact date instead.

Privacy

Birth data is personal data. The API reads it, computes, answers and forgets it: no request body is stored, and nothing you send is used for anything but the response. What we keep per request is the endpoint, the status code and the latency. See the privacy policy.

Questions