Natal Charts

Calculate complete natal charts with planetary positions, house cusps, and aspects.

Basic Calculation

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",
    "location": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }'

Parameters

Parameter	Type	Required	Description
dateTime	string	Yes	Date/time in YYYY-MM-DDTHH:mm format
location.latitude	number	Yes	Latitude (-90 to 90)
location.longitude	number	Yes	Longitude (-180 to 180)
location.timezone	string	Yes	IANA timezone identifier
houseSystem	string	No	House system (default: "placidus")
points	array	No	Celestial points to calculate (see Available Points below)
orbs	object	No	Custom orb values per aspect type (e.g., { "conjunction": 8, "opposition": 6 })
language	string	No	Language code for text content (default: "en")
includeText	boolean	No	Include interpretation text (default: false)
includeReadableEntities	boolean	No	Include human-readable entity titles (default: false)

House Systems

• placidus - Placidus (default)
• koch - Koch
• equal - Equal House
• whole - Whole Sign
• campanus - Campanus
• regiomontanus - Regiomontanus
• porphyry - Porphyry

Response

{
  "data": {
    "dateTime": "1990-06-15T12:30:00.000Z",
    "points": {
      "sun": {
        "pointId": "sun",
        "longitude": 84.5,
        "sign": "gemini",
        "signTitle": "Gemini",
        "degreesInSign": 24.5,
        "degreesInSignDms": [24, 30, 0],
        "houseNumber": 10,
        "houseId": "house-10",
        "retrograde": false,
        "pointTitle": "Sun",
        "houseTitle": "10th House"
      },
      "moon": {
        "pointId": "moon",
        "longitude": 245.2,
        "sign": "sagittarius",
        "signTitle": "Sagittarius",
        "degreesInSign": 5.2,
        "degreesInSignDms": [5, 12, 0],
        "houseNumber": 4,
        "houseId": "house-4",
        "retrograde": false,
        "pointTitle": "Moon",
        "houseTitle": "4th House"
      }
    },
    "houses": {
      "cusps": [
        { "longitude": 180.5, "longitudeDms": { "degrees": 180, "minutes": 30, "seconds": 0 }, "sign": "libra" },
        { "longitude": 210.3, "longitudeDms": { "degrees": 210, "minutes": 18, "seconds": 0 }, "sign": "scorpio" }
      ],
      "ascmc": [
        { "longitude": 180.5, "longitudeDms": { "degrees": 180, "minutes": 30, "seconds": 0 }, "sign": "libra" },
        { "longitude": 270.2, "longitudeDms": { "degrees": 270, "minutes": 12, "seconds": 0 }, "sign": "capricorn" }
      ]
    },
    "aspects": [
      {
        "pointA": "sun",
        "pointB": "moon",
        "aspect": "opposition",
        "angle": 160.7,
        "orb": 0.7,
        "applying": false,
        "pointATitle": "Sun",
        "pointBTitle": "Moon",
        "aspectTitle": "Opposition"
      }
    ],
    "chart": {
      "url": "https://api.astroapi.cloud/api/chart2/natal.svg?..."
    }
  }
}

House Cusps

Each cusp object includes longitude (ecliptic degrees), longitudeDms (degrees/minutes/seconds), and sign (zodiac sign ID). The first cusp (cusps[0]) is the Ascendant. The ascmc array contains the Ascendant, MC, ARMC, and Vertex.

Available Points

Use the points parameter to select which celestial points to calculate. If omitted, the default set is used.

Default Points

sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, meanNode, trueNode, meanApogee, osculatingApog

All Available Points

Point ID	Description
sun	Sun
moon	Moon
mercury	Mercury
venus	Venus
mars	Mars
jupiter	Jupiter
saturn	Saturn
uranus	Uranus
neptune	Neptune
pluto	Pluto
meanNode	Mean North Node
trueNode	True North Node
meanApogee	Mean Black Moon Lilith
osculatingApog	True Black Moon Lilith
chiron	Chiron
pholus	Pholus
ceres	Ceres
pallas	Pallas
juno	Juno
vesta	Vesta
interpolatedLunarApogee	Interpolated Lunar Apogee (Natural Apogee)
interpolatedLunarPerigee	Interpolated Lunar Perigee (Priapus)
earth	Earth

Example: Calculate Only Sun and Mars

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",
    "location": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "points": ["sun", "mars"]
  }'

The response will have sun and mars in the points object, and all four angles in the angles object:

{
  "data": {
    "points": {
      "sun": { "pointId": "sun", "longitude": 84.5, "sign": "gemini", ... },
      "mars": { "pointId": "mars", "longitude": 12.3, "sign": "aries", ... }
    },
    "angles": {
      "ascendant": {
        "pointId": "ascendant",
        "longitude": 180.5,
        "degreesInSign": 0.5,
        "degreesInSignDms": [0, 30, 0],
        "sign": "libra"
      },
      "descendant": { "pointId": "descendant", "longitude": 0.5, "sign": "aries", ... },
      "midheaven": { "pointId": "midheaven", "longitude": 270.2, "sign": "capricorn", ... },
      "imumCoeli": { "pointId": "imumCoeli", "longitude": 90.2, "sign": "cancer", ... }
    },
    "houses": { ... },
    "aspects": [ ... ]
  }
}

Angles

All four angles (ascendant, descendant, midheaven, imumCoeli) are always included in the angles object, regardless of the points parameter. Angles are derived from house calculations, not from ephemeris, so they have a simpler structure (no speed or retrograde data). The ascmc array in the houses response also always contains the raw angle longitudes.

Moon & Sun

Calculate moon phase, illumination, rise/set times, and sun position data.

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

Parameters

Parameter	Type	Required	Description
dateTime	string	Yes	Date/time in YYYY-MM-DDTHH:mm format
location.latitude	number	Yes	Latitude (-90 to 90)
location.longitude	number	Yes	Longitude (-180 to 180)
location.timezone	string	Yes	IANA timezone identifier

Required Module

This endpoint requires the module:moon module.

Response

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

Calculation Precision

AstroAPI reads NASA's JPL DE442 ephemeris directly for sub-milliarcsecond planetary positions. See the Calculation Accuracy page for full details on our data sources and corrections.