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

Parameters

Parameter	Type	Required	Description
datetime	string	Yes	ISO 8601 datetime
latitude	number	Yes	Latitude (-90 to 90)
longitude	number	Yes	Longitude (-180 to 180)
timezone	string	Yes	IANA timezone identifier
houseSystem	string	No	House system (default: "placidus")

House Systems

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

Response

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

Included Bodies

By default, the following celestial bodies are included:

• Sun, Moon
• Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
• North Node, South Node
• Chiron, Lilith (Black Moon)
• Part of Fortune

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 uses the Swiss Ephemeris for high-precision calculations. All positions are calculated to arcsecond accuracy.

Beta: Alternative Calculation Engine

Experimental Feature

This feature is in beta and may have accuracy issues. Use with caution in production environments.

AstroAPI offers an alternative calculation engine (calc2) that uses a custom implementation to read and evaluate Swiss Ephemeris SE1 data files directly, instead of using the official Swiss Ephemeris library. This engine is optimized for speed and may provide faster response times.

To use the alternative engine, include the X-Use-Calc2 header in your request:

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

Key Differences

Aspect	Standard Engine	Calc2 Engine (Beta)
Implementation	Swiss Ephemeris	Custom implementation
Data Source	SE1 ephemeris files	SE1 ephemeris files (same data)
Speed	Standard	Potentially faster
Accuracy	Arcsecond precision (reference)	May have minor deviations
Status	Production-ready	Beta

When to Use Calc2

• Recommended for: High-volume applications where speed is prioritized over absolute precision
• Not recommended for: Applications requiring maximum astronomical accuracy

Known Limitations

• Custom implementation may produce slightly different results compared to the official Swiss Ephemeris library
• Still under active development and testing
• Results should be validated against the standard engine for critical applications