Birth Chart API
Cosmic Ephemeris uses Western (tropical), geocentric astrology by default. Sidereal or Vedic-style calculations are not applied unless explicitly enabled and documented.
Generate natal astrology charts using API key authentication. Designed for passive, server-to-server usage.
Endpoint
POST https://api.cosmicephemeris.com/api/astro/birth-chart
Include Authorization: Bearer <API_KEY>.
Required Request Fields
date— ISO date (YYYY-MM-DD)time— 24-hour time (HH:MM)lat— latitude (decimal)lon— longitude (decimal)
Add an IANA timezone such as America/Los_Angeles when
the submitted time is local. If omitted, the engine interprets the time as UTC.
Standard date strings support 1800-01-01 through 2200-12-31.
Historical birth charts: 1000 BCE–2500 CE
For Western (tropical) or Vedic (sidereal) birth charts, supply an explicit date object. BCE (BC) counts backward; CE (AD) counts forward. There is no year zero. Choose Julian or Gregorian explicitly; both are proleptic, without an automatic calendar reform.
{
"date": {"year": 1000, "era": "BCE", "month": 1, "day": 1, "calendar": "proleptic_julian"},
"time": "12:00", "timezone": "UT1+05:30",
"lat": 28.6, "lon": 77.2, "zodiac": "sidereal", "ayanamsa": "lahiri"
}
UT1 means Greenwich mean solar time. A fixed offset such as
UT1+05:30 must be supplied from your source; this example does not claim that modern
Indian Standard Time applied in antiquity. Offsets may include seconds and cannot exceed 14 hours.
Historical mode rejects UTC/IANA timezone assumptions. It estimates TT using Skyfield's Delta-T model;
uncertain ancient/future time affects houses, Ascendant and classifications. Traditional Indian calendar
input is not automatically converted.
DE441 supplies ancient positions; DE440 is used from the padded January 1550 handoff onward.
Historical mode covers all 77 date-bearing calculation operations,
including chart JSON/SVG, supported timing tools and fact-report exports. Historical houses admit
all 25 documented choices; Gauquelin sectors remain Houses-only, and undefined geometry fails
without fallback. Mean/reference and dynamic stellar ayanamsas are available where the selected
operation supports them; this is not independent accuracy certification across the entire range.
Chart nodes.true uses the geometric osculating north-node model;
nodes.mean and its opposite nodes.south retain the mean-node model.
Rahu/Ketu remain mean nodes. See the node conventions
and read chart.metadata.warnings.
Saved profiles preserve era, calendar and offset; JSON exports containing historical dates use version 2.
Returns
- Planetary positions (Sun through Pluto)
- Ascendant and Midheaven (
mc) - Whole Sign (
whole_sign) and Equal (equal) house systems - Aspects, lunar nodes, and metadata
All calculation results are returned inside the chart object.
Example Response
This verified engine response is abbreviated; planets include additional motion fields, and the full response also includes aspects, nodes, and metadata.
{
"type": "birth-chart",
"input": {
"date": "1995-11-08",
"time": "14:22",
"lat": 34.05,
"lon": -118.24,
"timezone": "UTC"
},
"chart": {
"status": "ok",
"planets": {
"Sun": { "lon": 225.7013, "sign": "Scorpio" },
"Moon": { "lon": 60.2319, "sign": "Gemini" }
},
"houses": {
"ascendant": 225.4957,
"mc": 142.2011,
"systems": {
"whole_sign": {
"houses": {
"1": 210.0,
"2": 240.0,
"3": 270.0,
"4": 300.0,
"5": 330.0,
"6": 0.0,
"7": 30.0,
"8": 60.0,
"9": 90.0,
"10": 120.0,
"11": 150.0,
"12": 180.0
}
},
"equal": {
"houses": {
"1": 225.4957,
"2": 255.4957,
"3": 285.4957,
"4": 315.4957,
"5": 345.4957,
"6": 15.4957,
"7": 45.4957,
"8": 75.4957,
"9": 105.4957,
"10": 135.4957,
"11": 165.4957,
"12": 195.4957
}
}
}
}
}
}
Quick Test / curl
Use this curl command from a trusted server to test the Birth Chart endpoint:
curl -i https://api.cosmicephemeris.com/api/astro/birth-chart \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${COSMICEPHEMERIS_KEY}" \
-d '{
"date": "2000-01-01",
"time": "12:00",
"lat": 33.7488,
"lon": -84.3877,
"timezone": "America/New_York"
}'
Common Uses
- Chart visualization
- User profiles
- Compatibility systems
- Astrology dashboards
All calculation results are returned as raw data. Interpretation, weighting, and scoring are the responsibility of the client application or downstream services.
// Node.js 22+ — server-side only
fetch("https://api.cosmicephemeris.com/api/astro/birth-chart", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.COSMICEPHEMERIS_KEY}`
},
body: JSON.stringify({
date: "1995-11-08",
time: "14:22",
lat: 34.05,
lon: -118.24,
timezone: "America/Los_Angeles"
})
})
.then(res => res.json())
.then(data => console.log(data));
# Python — Birth Chart API
import os
import requests
url = "https://api.cosmicephemeris.com/api/astro/birth-chart"
payload = {
"date": "1995-11-08",
"time": "14:22",
"lat": 34.05,
"lon": -118.24,
"timezone": "America/Los_Angeles"
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['COSMICEPHEMERIS_KEY']}"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())