NatalEngine

Birth chart calculation engine for Western Astrology, Human Design, and Gene Keys.

Returns clean, structured data for apps and AI integrations. No interpretation, just the facts.

Install

npm install natalengine

Quick Start

import {
  calculateAstrology,
  calculateHumanDesign,
  calculateGeneKeys
} from 'natalengine';

// Western Astrology
const astro = calculateAstrology('1990-06-15', 14.5, -5, 40.7128, -74.0060);
console.log(astro.sun.sign.name);        // "Gemini"
console.log(astro.moon.sign.name);       // "Pisces"
console.log(astro.rising.sign.name);     // "Libra"
console.log(astro.planets.venus.degree); // "19°08'41\""

// Human Design
const hd = calculateHumanDesign('1990-06-15', 14.5, -5);
console.log(hd.type.name);               // "Manifestor"
console.log(hd.authority.name);          // "Emotional Authority"
console.log(hd.profile.numbers);         // "2/4"
console.log(hd.channels);                // [{ gates: [12, 22], name: "..." }]

// Gene Keys
const gk = calculateGeneKeys(hd);
console.log(gk.activationSequence.lifeWork.gift);  // "Discrimination"
console.log(gk.activationSequence.lifeWork.shadow); // "Vanity"
console.log(gk.activationSequence.lifeWork.siddhi); // "Purity"

API

calculateAstrology(birthDate, birthHour, timezone, latitude?, longitude?)

Returns Western natal chart data.

Parameter	Type	Description
birthDate	string	YYYY-MM-DD format
birthHour	number	Decimal hours (14.5 = 2:30 PM)
timezone	number	UTC offset (-5 for EST)
latitude	number	Optional. Required for accurate Rising sign
longitude	number	Optional. Required for accurate Rising sign

Returns:

{
  sun: { sign, degree, longitude },
  moon: { sign, degree, longitude },
  rising: { sign, degree, longitude, accurate },
  planets: {
    mercury: { sign, degree, longitude },
    venus: { sign, degree, longitude },
    mars: { sign, degree, longitude },
    jupiter: { sign, degree, longitude },
    saturn: { sign, degree, longitude },
    uranus: { sign, degree, longitude },
    neptune: { sign, degree, longitude },
    pluto: { sign, degree, longitude }
  },
  nodes: {
    north: { sign, degree, longitude },
    south: { sign, degree, longitude }
  },
  midheaven: { sign, degree, longitude },
  aspects: [
    { planet1, planet2, aspect, orb, applying }
  ],
  balance: {
    elements: { fire, earth, air, water },
    modalities: { cardinal, fixed, mutable },
    dominantElement,
    dominantModality
  }
}

calculateHumanDesign(birthDate, birthHour, timezone, options?)

Returns Human Design chart data. options.nodeType selects 'true' (default, the dominant HD convention) or 'mean' lunar nodes.

Every activation includes the full substructure — gate, line, color, tone, base, and the raw longitude — so apps can build Variable/PHS features or re-derive anything.

Returns:

{
  type: { name, strategy, authority, notSelf, signature },
  authority: { name, description },
  profile: { numbers, name, theme },
  definition: "Single Definition" | "Split Definition" | "Triple Split" | "Quadruple Split",
  incarnationCross: { name, gates, theme },
  centers: {
    defined: [{ name, theme, biological }],
    undefined: [{ name, theme, biological }],
    definedNames: ["Sacral", "Throat", ...],
    undefinedNames: ["Head", "Ajna", ...]
  },
  gates: {
    personality: { sun, earth, moon, northNode, southNode, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto },
    design: { sun, earth, moon, northNode, southNode, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto },
    all: [1, 2, 3, ...]
  },
  channels: [{ gates, name, centers, circuit, subcircuit }],
  circuitAnalysis: { individual, tribal, collective, integration, dominant },
  variable: {
    determination: { arrow, color, tone, name, description, cognition },
    environment:   { arrow, color, tone, name, description },
    motivation:    { arrow, color, tone, name, description },
    perspective:   { arrow, color, tone, name, description },
    notation: "RR LR"  // [Determination, Environment | Motivation, Perspective]
  },
  meta: { birthDate, birthHour, timezone, nodeType, ephemeris, designSolarArc },
  positions: {
    personality: { date, sun, earth, moon, ... },     // Raw planetary data at birth
    design: { date, dateTime, sun, earth, moon, ... } // Raw data at exactly 88° solar arc before
  }
}

calculateGeneKeys(humanDesignData)

Returns Gene Keys profile from Human Design data.

Returns:

{
  activationSequence: {
    lifeWork: { key, line, keyLine, shadow, gift, siddhi },
    evolution: { key, line, keyLine, shadow, gift, siddhi },
    radiance: { key, line, keyLine, shadow, gift, siddhi },
    purpose: { key, line, keyLine, shadow, gift, siddhi }
  },
  venusSequence: {
    attraction: { key, line, keyLine, shadow, gift, siddhi },
    iq: { key, line, keyLine, shadow, gift, siddhi },
    eq: { key, line, keyLine, shadow, gift, siddhi },
    sq: { key, line, keyLine, shadow, gift, siddhi }
  },
  pearlSequence: {
    vocation: { key, line, keyLine, shadow, gift, siddhi },
    culture: { key, line, keyLine, shadow, gift, siddhi },
    pearl: { key, line, keyLine, shadow, gift, siddhi }
  },
  core: { ... },       // Same as vocation (Design Mars) - Venus Sequence lens
  brand: { ... },      // Same as lifeWork (Personality Sun) - Pearl Sequence lens
  allKeys: [...],      // All 11 Gene Keys in the profile
  primeGifts: [...],   // The 4 gifts from Activation Sequence
  summary: "Life's Work: 64.3 (Imagination), ..."
}

Timezone & geocoding (accurate birth data)

The largest real-world error source in birth charts is timezone handling — historical DST, wartime time, half-hour zones. Never estimate offsets from longitude. NatalEngine ships the accurate path:

import { searchPlaces, resolveUtcOffset, formatUtcOffset } from 'natalengine';

const places = await searchPlaces('Denver');     // Open-Meteo geocoding, no key
// → [{ name, label, latitude, longitude, timezone: 'America/Denver', ... }]

const offset = resolveUtcOffset('1944-06-15', '12:00', 'Europe/London');
// → 2 (British Double Summer Time — full IANA history via the Intl API)

const hd = calculateHumanDesign('1944-06-15', 12, offset);

Human Design extras

import { calculateHDTransits, compareHumanDesign, analyzePenta } from 'natalengine';

const transits = calculateHDTransits(hd, '2026-06-04'); // transit overlay + channel completions
const connection = compareHumanDesign(hdA, hdB);        // electromagnetic/dominance/compromise/companionship
const team = analyzePenta([hdA, hdB, hdC], names);      // group/Penta analysis

MCP Server (AI Integration)

NatalEngine includes an MCP server for Claude and other AI assistants.

Usage with Claude Code

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "natalengine": {
      "command": "npx",
      "args": ["natalengine-mcp"]
    }
  }
}

Then ask Claude:

"Calculate my birth chart for June 15, 1990 at 2:30 PM in New York"

Available Tools

Tool	Description
calculate_natal_chart	Complete profile (all 3 systems)
calculate_astrology	Western natal chart
calculate_human_design	Human Design chart
calculate_gene_keys	Gene Keys profile
get_planetary_positions	Raw planetary longitudes

Accuracy

• Planetary positions: VSOP87 via astronomy-engine
• Accuracy: ±1 arcminute
• Ascendant: Calculated from local sidereal time
• Human Design: 88° solar arc for design calculation

What's Included

System	Data
Astrology	Sun, Moon, Rising, all planets, nodes, midheaven, aspects, elements, modalities
Human Design	Type, Strategy, Authority, Profile, Definition, Centers, Gates (13 planets × 2 with line/color/tone/base), Channels with circuitry, Incarnation Cross (192 named), Variable (4 arrows / PHS), Transits, Connection charts, Penta
Gene Keys	Activation Sequence, Venus Sequence, Pearl Sequence with shadow/gift/siddhi

What's NOT Included

• Long-form interpretations or readings (keynote-level descriptions are included)
• Progressed charts
• Solar/Saturn returns (planned)

License

MIT