@earthpulsenow/birth-chart-calculator

A JavaScript and Node.js birth chart calculator powered by astronomical planet position calculations. Generate natal chart data including zodiac signs, planetary positions, houses, aspects, ascendant, and chart summary from birth date, time, and location.

Live demo: https://earthpulsenow.com/birth-chart-calculator

This package is currently organized as an internal module inside the EarthPulseNow production app. It is structured for future npm publishing, but private: true remains enabled to prevent accidental publication of the full site project.

Features

• Birth chart calculator for Node.js and Express apps
• Tropical zodiac placements from ecliptic longitude
• Sun sign, moon sign, rising sign, planet degrees, and retrograde status
• House cusps with Swiss Ephemeris when available and documented fallbacks
• Major aspects: conjunction, sextile, square, trine, and opposition
• UTC conversion from birth date, birth time, and IANA timezone
• Input validation with helpful errors
• JSON API response suitable for frontend birth chart displays

Installation

When published to npm:

npm install @earthpulsenow/birth-chart-calculator

Inside this repository, import from the local module:

import { calculateBirthChart } from './src/astrology/index.js';

Basic Usage

import { calculateBirthChart } from '@earthpulsenow/birth-chart-calculator';

const result = await calculateBirthChart({
  date: '1994-05-17',
  time: '15:48',
  lat: 7.4863,
  lon: 80.3623,
  timezone: 'Asia/Colombo'
});

console.log(result.chart.sunSign);
console.log(result.chart.moonSign);
console.log(result.chart.ascendant);

Express API Example

import express from 'express';
import { birthChartApiResponse } from '@earthpulsenow/birth-chart-calculator';

const app = express();

app.get('/api/birth-chart', async (req, res) => {
  const response = await birthChartApiResponse(req.query);
  res.status(response.status).json(response.body);
});

Example request:

/api/birth-chart?date=1994-05-17&time=15:48&lat=7.4863&lon=80.3623&timezone=Asia/Colombo

Example Response

{
  "success": true,
  "input": {
    "date": "1994-05-17",
    "time": "15:48",
    "timezone": "Asia/Colombo",
    "lat": 7.4863,
    "lon": 80.3623,
    "houseSystem": "Placidus",
    "utc": "1994-05-17T10:18:00.000Z"
  },
  "chart": {
    "sunSign": "Taurus",
    "moonSign": "Leo",
    "ascendant": "Virgo",
    "planets": [],
    "houses": [],
    "aspects": [],
    "summary": {}
  },
  "meta": {
    "engine": "Swiss Ephemeris with Astronomy Engine fallback",
    "source": "EarthPulseNow",
    "url": "https://earthpulsenow.com/birth-chart-calculator"
  }
}

Input Parameters

| Name | Required | Description | | --- | --- | --- | | date | Yes | Birth date in YYYY-MM-DD format. | | time | Yes | Birth time in HH:mm 24-hour format. | | lat | Yes | Birth latitude, between -90 and 90. | | lon | Yes | Birth longitude, between -180 and 180. | | timezone | Yes | IANA timezone string, for example Asia/Colombo. | | houseSystem | No | Placidus, Whole Sign, Equal House, or Koch. Defaults to Placidus. | | aspects | No | Boolean-like value. Defaults to true. |

Output Fields

• chart.sunSign, chart.moonSign, and chart.ascendant
• chart.planets[] with sign, degree, longitude, house, speed, and retrograde status
• chart.houses[] with house number, sign, degree, and longitude
• chart.aspects[] with planet pair, aspect type, orb, and strength
• chart.summary with big three, dominant elements, modalities, and house calculation notes

Accuracy Notes

The module uses Swiss Ephemeris when the optional local package is available and falls back to Astronomy Engine plus deterministic approximations where needed. Timezone conversion is based on the supplied IANA timezone, not the server or user's current timezone.

House cusps for Placidus and Koch depend on Swiss Ephemeris support. If exact house cusps are unavailable, the response includes a warning and uses an approximate fallback. Unsupported or uncertain behavior is documented instead of faked.

Limitations

• Tropical zodiac calculations are supported. Sidereal mode is not enabled.
• Astrology interpretations are minimal and should be written by the host app.
• No paid APIs are used.
• Results are not scientific, medical, financial, or legal advice.

SEO Keywords

This project supports developer searches for birth chart calculator, natal chart calculator, astrology chart calculator, zodiac chart, sun sign, moon sign, rising sign, ascendant calculator, planetary positions, astrology JavaScript library, and Node.js astrology calculator.

Development

npm install
npm test
npm run build
npm run dev

The production EarthPulseNow page remains available at:

/birth-chart-calculator

The developer API endpoint is:

GET /api/birth-chart

License

MIT. Copyright EarthPulseNow.