Back to Docs
Natal Chart (Western)
Natal Chart (Western)
POST
/api/v1/natal/calculateGenerate a professional Western Natal Chart with support for multiple house systems, precise planetary speeds, station detection, extra bodies (Asteroids & Nodes), and explicit untimed birth support via time_known.
Full URL
https://api.freeastroapi.com/api/v1/natal/calculateSafe retries with Idempotency-Key
Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.
A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.
Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.
Request Body Parameters
| Parameter | Type | Req | Description |
|---|---|---|---|
| name | string | No | Subject name (for display purposes) |
| year | integer | Yes | Birth year (e.g., 1990) |
| month | integer | Yes | Birth month (1-12) |
| day | integer | Yes | Birth day (1-31) |
| time_known | boolean | No | Default: true. Set false when the birth time is unknown. In that mode, houses and angles are omitted, planet house placements are not returned, and confidence metadata is downgraded. |
| hour | integer | No | Birth hour (0-23, 24-hour format). Required when time_known=true. Ignored structurally when time_known=false. |
| minute | integer | No | Birth minute (0-59). Required when time_known=true. Ignored structurally when time_known=false. |
| city | string | Yes | City name (used for coordinate lookup via /geo/search) |
| lat | float | No | Latitude (-90 to 90). Optional: auto-resolved from city if not provided |
| lng | float | No | Longitude (-180 to 180). Optional: auto-resolved from city if not provided |
| tz_str | string | No | Timezone string (e.g. 'Europe/Paris' or 'AUTO'). Default: AUTO |
| house_system | string | No | placidus (default), whole_sign, equal, koch, regiomontanus, porphyry, campanus |
| zodiac_type | string | No | tropical (default) or sidereal. Sidereal uses the specified ayanamsa. |
| fixed_stars | array[str] | No | Preferred fixed-star selector. Accepts pack ids such as royal_4 and behenian_20, exact star names such as Spica, or all for the full default set. Example: ["royal_4", "Spica"]. . |
Sample Code
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",
"response_format": "full",
"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 & Optimization v2.2
Compression
We support Brotli (br) compression for maximum speed. Ensure your client sends Accept-Encoding: br, gzip.
Caching
Natal charts are immutable. Responses include Cache-Control: public, max-age=31536000, immutable. You can safely cache results indefinitely to minimize API calls.
Response Data
{
"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..."
}
]
}
}
} Untimed Response Example
{
"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
Does this endpoint provide a visual chart as SVG or PNG?
No. The Natal endpoint returns calculated chart data only; it does not generate visual chart images in SVG or PNG. Use the Western Chart SVG endpoint when you need a visual chart.
Does your API return parallels?
Yes. The Natal endpoint can return declination parallels and contra-parallels when you opt in with"include_declination_aspects": true. They are not returned by default.
{
"include_declination_aspects": true,
"declination_orb": 1.0
}Results are returned under declination_aspects and summarized indeclination_aspects_summary. Regular longitude aspects remain underaspects.