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())