npm package:
free-human-design· live site: freehumandesign.netlify.app
The free Human Design API & Gene Keys API — the most tested, most accurate, pure-JavaScript engine of its kind, with extended astrology. From the maintainer of the official Gene Keys Profiler and Event Horizon Election Engine, and Gene Key's Integral Human Design.
From a birth date, time and timezone (and an optional location), free-human-design
computes:
- 🧬 Gene Keys — the gene key (hexagram) + line for every sphere of the
Hologenetic Profile (
lifeswork,purpose,pearl,iq,eq, …). - ⚡ Human Design — the full bodygraph: every planetary gate activation (13 bodies × Personality + Design), activated gates, defined channels, defined centers, open centers, and the derived Type, Authority and Profile.
- 🪐 Astrology — Ascendant, Descendant, Midheaven (MC), IC, and house cusps (Placidus, Whole Sign or Equal).
It is pure JavaScript — no native build, no node-gyp, and no ephemeris
data files. Planetary positions come from the MIT-licensed
astronomia package (VSOP87 + lunar
theory), validated to the exact gate/line against Swiss Ephemeris.
npm install free-human-designconst { computeChart } = require('free-human-design');
const chart = computeChart({
birthdate: '1972-08-02', // YYYY-MM-DD (or YYYY-M-D)
birthtime: '14:30', // HH:mm (or H:mm, or HH:mm:ss)
timezone: 'Asia/Bangkok', // any IANA timezone
// location: { lat: 13.75, lng: 100.5 }, // optional — see "Location" below
// houseSystem: 'placidus', // 'placidus' | 'whole' | 'equal'
});
console.log(chart.humanDesign.type); // 'Manifesting Generator'
console.log(chart.humanDesign.authority); // 'Sacral'
console.log(chart.humanDesign.profile); // '3/5'
console.log(chart.geneKeys.spheres.lifeswork); // { gk: 33, line: 3 }
console.log(chart.astrology.angles.ascendant.sign); // 'Sagittarius'computeChart returns three coherent sections:
If no location can be resolved, astrology is null (everything else still
computes — astrology is the only part that needs a place of birth).
freehumandesign.netlify.app — a free, local-only
API and an in-browser playground. Every endpoint is a plain GET with open CORS,
so you can call it from a browser, a notebook, or hand it straight to an AI.
curl "https://freehumandesign.netlify.app/api/chart?date=1972-08-02&time=14:30&tz=Asia/Bangkok"| Endpoint | Returns |
|---|---|
/api/chart |
Full chart — Gene Keys + Human Design + Astrology |
/api/genekeys |
Gene Keys spheres |
/api/humandesign |
Human Design bodygraph |
/api/astrology |
Ascendant / MC / houses |
/api/midpoints |
Advanced — the midpoint matrix over the 26 activations |
/api/prompt |
A ready-to-paste AI interpretation prompt |
/api/timezones?q=bali |
IANA timezone search |
Params: date=YYYY-MM-DD · time=HH:mm · tz=IANA · [lat lng house=placidus|whole|equal midpoints=1]
Dark and light, fully responsive:
| Dark | Light |
|---|---|
 |
 |
The site and API live in site/ and netlify/functions/;
the deploy config is netlify.toml. Nothing about a birth ever
leaves the function — the ephemeris is computed in-process.
Each sphere is keyed by its gene key (gk, the I-Ching hexagram 1–64) and line
(1–6), mapped from a planet at the Personality (birth) or Design (~88° of solar
arc before birth) moment:
| Sphere | Source | Sphere | Source |
|---|---|---|---|
lifeswork |
Personality Sun | attraction |
Design Moon |
evolution |
Personality Earth | sq |
Design Venus |
radiance |
Design Sun | core |
Design Mars |
purpose |
Design Earth | culture |
Design Jupiter |
iq |
Personality Venus | stability |
Design Saturn |
eq |
Personality Mars | creativity |
Design Uranus |
pearl |
Personality Jupiter | relating |
Personality Mercury |
The bodygraph is derived from 26 activations — 13 bodies (Sun, Earth, Moon, North/South Node, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) at both the Personality and Design moments:
const { computeChart } = require('free-human-design');
const hd = computeChart({ birthdate: '1972-08-02', birthtime: '14:30', timezone: 'Asia/Bangkok' }).humanDesign;
hd.activatedGates; // [4, 10, 11, … ] — every gate lit by a planet
hd.definedChannels; // channels where BOTH gates are activated
hd.definedCenters; // centers touched by a defined channel
hd.openCenters; // the rest
hd.type; // Generator | Manifesting Generator | Projector | Manifestor | Reflector
hd.authority; // Emotional | Sacral | Splenic | Ego | Self-Projected | Mental | Lunar
hd.profile; // e.g. '3/5' (Personality Sun line / Design Sun line)Reference data (gate→center map and the 36 channels) is the standard Human Design bodygraph and is exported for your own use:
const { GATE_CENTER, CHANNELS, CENTERS, computeBodygraph } = require('free-human-design');const { computeAngles, computeHouses } = require('free-human-design');
const angles = computeAngles({ jdUT: 2441531.8125, lat: 13.75, lng: 100.5 });
// { ascendant, descendant, mc, ic } — each with longitude, sign, degInSign, gateLine
const houses = computeHouses({ jdUT: 2441531.8125, lat: 13.75, lng: 100.5, system: 'placidus' });
// { system, cusps: [{ house, longitude, sign, degInSign }, …], angles }Angles and houses need only sidereal time + obliquity (no ephemeris). Placidus falls back to Whole Sign above the polar circle, where it is mathematically undefined.
A midpoint is the point on the ecliptic exactly halfway between two bodies, along the shorter of the two arcs joining them (the astrological convention):
midpoint(a, b) = normalize(a + signedAngleDiff(b, a) / 2)
Each midpoint is mapped back onto the Gene Keys wheel (gate.line) like any other
point. Midpoints are opt-in — off by default (the matrix is O(n²)):
const { computeChart, computeMidpoints } = require('free-human-design');
const chart = computeChart({
birthdate: '1992-12-09', birthtime: '00:35', timezone: 'Europe/Brussels',
midpoints: true, // ← attaches chart.humanDesign.midpoints
});
chart.humanDesign.midpoints._meta; // { count: 26, pairCount: 325, method: 'shortest-arc' }
chart.humanDesign.midpoints.pairs[0]; // { a: 'p_sun', b: 'p_earth', longitude, gate, line, color }
chart.humanDesign.midpoints.matrix; // 26×26, symmetric, null diagonal
// Or feed it any labelled points yourself:
computeMidpoints([{ key: 'asc', longitude: 25.3 }, { key: 'mc', longitude: 282.7 }]);The point set is the 26 Human Design activations (13 bodies × Personality +
Design), keyed p_<body> / d_<body>, giving 26·25/2 = 325 pairs. Over REST:
curl "https://freehumandesign.netlify.app/api/chart?date=1992-12-09&time=00:35&tz=Europe/Brussels&midpoints=1"
curl "https://freehumandesign.netlify.app/api/midpoints?date=1992-12-09&time=00:35&tz=Europe/Brussels"The live site's astrology wheel has a ✳ Midpoints toggle that overlays all 325
midpoints as a ring. Generate a standalone HTML view (crossings + matrix + toggle)
with scripts/gen-crossings.js.
The astrology section needs a place of birth. You have two options:
- Explicit coordinates (most accurate):
computeChart({ /* … */ location: { lat: 13.7563, lng: 100.5018 } });
- Just the timezone —
free-human-designderives a representative location from the most-populous city in that timezone, which is plenty for an Ascendant:computeChart({ birthdate, birthtime, timezone: 'Asia/Bangkok' }); // → location { city: 'Bangkok', lat: 13.75, lng: 100.51, source: 'timezone-city' }
Coordinates use north-positive latitude and east-positive longitude.
Birth charts are historical, so the engine honours the full IANA history of
each zone — not just modern rules. Offsets resolve through
Luxon against the runtime's IANA/ICU tz
database, which correctly handles 20th-century edge cases such as US year-round
DST in 1974, British Double Summer Time (1944/1947 = UTC+2), Poland skipping DST
in 1970, Nepal's 1986 switch to UTC+5:45, and pre-standardisation Local Mean
Time. These are regression-locked in
test/timezone-history.test.js.
Accuracy of historical offsets depends on the tz database in your JS runtime. Use a current Node.js (full ICU is the default since Node 13) for complete 20th-century coverage. Nonexistent local times (spring-forward gaps) shift forward into DST; ambiguous times (fall-back overlaps) resolve to the earlier offset.
const { searchTimezones, locationForTimezone } = require('free-human-design');
searchTimezones('bali'); // → [{ ianaName: 'Asia/Makassar', mainCity: 'Makassar', … }]
searchTimezones('tokyo'); // → [{ ianaName: 'Asia/Tokyo', currentOffsetMinutes: 540, … }]
locationForTimezone('Europe/London'); // → { lat: 51.5, lng: -0.12, city: 'London', … }# Full chart (readable summary)
npx free-human-design --chart --date 1972-08-02 --time 14:30 --tz Asia/Bangkok
# With explicit coordinates and a house system, as JSON
npx free-human-design --chart --date 1972-08-02 --time 14:30 --tz Asia/Bangkok \
--lat 13.75 --lng 100.5 --house whole --json
# Classic profile (p_/d_ + spheres)
npx free-human-design --date 1972-08-02 --time 14:30 --tz Asia/Bangkok
# Timezone search
npx free-human-design --tz-search baliPlanetary positions come from astronomia (VSOP87 + lunar theory) and match
Swiss Ephemeris to well within a Gene Keys line (0.9375°): typically <1″
for the Sun and planets and ~10″ for the Moon. The gate/line/retrograde output
is regression-locked against Swiss Ephemeris golden vectors (see
test/profile.test.js) and validated against five
real charts from a third-party calculator — 125 of 130 body activations match
to the exact gate.line, with the remainder within a single line (design-Moon
timing, true-node algorithm and sub-line ephemeris differences between
calculators). See test/reference-charts.test.js.
Lunar nodes use the true node (oscillating), matching mainstream Human Design calculators.
The pure-JS heuristic was benchmarked against the official Swiss-Ephemeris Gene
Keys engine (genekeysExperimentalV2, the one the Hologenetic Profiler uses)
across 2,000 births spanning 1600–2200 AD and 30 timezones — 52,000 body
placements compared, binned by 20-year era
(scripts/deviation-study.js). Δ is the shortest
angular distance between the two ecliptic longitudes (1° = 60′).
Test method. For each of 2,000 deterministically-seeded births (random
month/day/time, a real IANA timezone + its city coordinates), the same local
time + timezone is sent to both engines. free-human-design places the 13 Human Design
bodies × 2 streams locally; the official engine is asked over HTTP; the two
ecliptic longitudes are compared body-by-body (Δ in arcminutes, plus gate/line
agreement), then aggregated into 20-year buckets. Every official response is
cached to scripts/data/, so the run is resumable and the reports re-render
offline. The comparison math is unit-tested against a committed real-API fixture
(test/deviation-sample.test.js) — no network in CI.
Headline — the Gene Keys profile spheres. A Hologenetic Profile only ever reads 14 spheres (Life's Work, Evolution, Radiance, Purpose, Relating, IQ, EQ, Pearl, Attraction, SQ, Core, Culture, Core Stability, Creativity). Those spheres never touch Pluto, Neptune, or the lunar nodes — the three bodies that dominate the deviation — so a real profile is far tighter than the raw all-body figure (28,000 sphere activations compared):
| Metric | Gene Keys spheres | All 26 bodies |
|---|---|---|
| Median Δ | 0.01′ (≈ 0.6″) | 0.02′ |
| p95 Δ | 0.17′ | 10.8′ |
| max Δ | 0.78′ | 74.8′ |
| Gate agreement | 99.4% | 98.8% |
| Line agreement | 95.6% | 92.6% |
Every sphere agrees on the gate 99.0–99.7% of the time and stays sub-arcminute at p95 across all 600 years — the largest is the Moon-based Attraction sphere at 0.56′, still well under a tenth of a Gene Keys line. Per sphere, all eras:
| Sphere | Body | Median Δ′ | p95 Δ′ | Gate% | Line% |
|---|---|---|---|---|---|
| Life's Work | p_sun | 0.01 | 0.02 | 99.5% | 95.2% |
| Evolution | p_earth | 0.01 | 0.02 | 99.5% | 95.2% |
| Radiance | d_sun | 0.02 | 0.04 | 99.3% | 96.1% |
| Purpose | d_earth | 0.02 | 0.04 | 99.3% | 96.1% |
| Relating | p_mercury | 0.01 | 0.02 | 99.4% | 96.3% |
| IQ | p_venus | 0.01 | 0.02 | 99.5% | 95.7% |
| EQ | p_mars | 0.01 | 0.02 | 99.3% | 96.0% |
| Pearl | p_jupiter | 0.01 | 0.02 | 99.0% | 96.0% |
| Attraction | d_moon | 0.27 | 0.56 | 99.7% | 95.3% |
| SQ | d_venus | 0.02 | 0.05 | 99.6% | 94.8% |
| Core | d_mars | 0.01 | 0.03 | 99.3% | 95.2% |
| Culture | d_jupiter | 0.01 | 0.02 | 99.3% | 95.8% |
| Core Stability | d_saturn | 0.01 | 0.03 | 99.5% | 95.6% |
| Creativity | d_uranus | 0.01 | 0.07 | 99.5% | 95.3% |
All 26 activations (diagnostic). Including the bodies a profile ignores, the overall median Δ is 0.02′, p95 10.8′, gate agreement 98.8%. The tail is dominated by Pluto (median 20.9′ — its multi-century orbit is the hardest to approximate) and, distantly, the lunar nodes. The Δ grows toward the window extremes (pre-1800 and post-2100), where ΔT and pre-1900 Local Mean Time are also less certain; the modern era (1880–2100) sits at gate ≥ 99%, p95 ≈ 4′.
Reproduce it (full report with the per-era chart in scripts/data/):
node scripts/deviation-study.js # full run (2000 births), caches to scripts/data/
node scripts/deviation-study.js --limit 5 # smoke test (first 5 births)
node scripts/deviation-study.js --report-only # re-render the report from cache, offlineField mapping — the official response ↔ free-human-design:
official genekeysExperimentalV2 |
free-human-design |
|---|---|
geneKeys.personality[] / .design[] |
humanDesign.activations.personality / .design |
…[i].planet.name (Sun, North Node, …) |
activation.body (sun, north_node, …) |
…[i].planet.position.location (absolute tropical °) |
activation.longitude |
…[i].information.number (gate) |
activation.gate |
…[i].geneKey fractional part (.3) |
activation.line |
…[i].planet.velocity sign |
activation.retrograde |
heliocentric.* |
(not modelled — free-human-design is geocentric) |
If you want Swiss Ephemeris precision (and accept its AGPL/commercial license), install it yourself and opt in — it is not a dependency of this package:
npm install swisseph # native build; provide ephemeris files via EPHE_PATH
EPHE_BACKEND=swisseph node your-app.jsfree-human-design auto-detects it and falls back to the pure-JS backend if it isn't
available.
| Export | Returns |
|---|---|
computeChart(input) |
Full { input, geneKeys, humanDesign, astrology, _meta } |
computeProfile(input) |
{ input, engine: { p_, d_, spheres, _meta } } (back-compat) |
computeBodygraph(activations) |
{ type, authority, profile, activatedGates, definedChannels, definedCenters, openCenters, centers, … } |
computeActivations({ birthUtc }) |
The 26 raw activations ({ personality, design }) |
computeMidpoints(points) |
Midpoint { points, pairs, matrix, _meta } over labelled { key, longitude } points |
computeAngles({ jdUT, lat, lng }) |
{ ascendant, descendant, mc, ic } |
computeHouses({ jdUT, lat, lng, system }) |
{ system, cusps, angles } |
searchTimezones(query, { limit }) |
Ranked IANA zones with offsets + city hints |
locationForTimezone(iana) |
Representative { lat, lng, city, country } |
parseBirthToUtc({ birthdate, birthtime, timezone }) |
UTC Date |
mapLongitudeDegrees(lon) |
{ hexagram, line, color } |
Also exported: GATE_CENTER, CHANNELS, CENTERS, signOf, SIGNS,
resolveLocation, getBackend.
npm test # run the suite
npm run coverage # run with a coverage report
npm run coverage:badge # refresh the coverage badge above from a fresh run247 tests covering: the mandala mapping, regression-locked profiles, the bodygraph reference data + derivation, the astronomia backend, the astrology angles/houses (verified against the horizon/meridian geometry), the location lookup, the end-to-end chart, the midpoint matrix, the deviation-study comparison math (against a committed official-engine fixture, no network), five real reference charts from a third-party Swiss-Ephemeris calculator, and historical IANA timezone offsets across the 20th century.
MIT © Adam Blvck / Blvck Studios. See LICENSE and NOTICE for third-party attributions.
{ "input": { "birthdate": "1972-08-02", "birthtime": "14:30", "timezone": "Asia/Bangkok", "birth_utc": "1972-08-02T07:30:00.000Z", "location": { "lat": 13.75, "lng": 100.51, "city": "Bangkok", "source": "timezone-city" } }, "geneKeys": { "spheres": { "lifeswork": { "gk": 33, "line": 3 }, "evolution": { "gk": 19, "line": 3 }, "radiance": { "gk": 24, "line": 5 }, "purpose": { "gk": 44, "line": 5 }, "iq": { "gk": 12, "line": 6 }, "eq": { "gk": 4, "line": 4 }, "pearl": { "gk": 10, "line": 2 }, "relating": { "gk": 4, "line": 1 }, "attraction": { "gk": 11, "line": 3 }, "sq": { "gk": 12, "line": 3 }, "core": { "gk": 12, "line": 1 }, "culture": { "gk": 58, "line": 5 }, "stability": { "gk": 16, "line": 1 }, "creativity": { "gk": 57, "line": 1 } } }, "humanDesign": { "type": "Manifesting Generator", "authority": "Sacral", "profile": "3/5", "definitionCount": 6, "activatedGates": [4, 10, 11, 12, 16, 19, 24, 33, 34, 44, 45, 48, 51, 56, 57, 58, 60, 61, 62], "definedChannels": [{ "key": "34-57", "gates": [34, 57], "centers": ["sacral", "spleen"], "name": "Power" }, "…"], "definedCenters": ["head", "ajna", "throat", "g", "sacral", "spleen"], "openCenters": ["heart", "solarplexus", "root"], "centers": { "head": true, "ajna": true, "…": "…" }, "p_": { "sun": { "gate": 33, "line": 3, "color": 4, "retrograde": false, "longitude": 130.09, "…": "…" }, "…": "…" }, "d_": { "…": "…" }, "activations": { "personality": [ "…13 bodies…" ], "design": [ "…13 bodies…" ] } }, "astrology": { "location": { "lat": 13.75, "lng": 100.51, "city": "Bangkok" }, "angles": { "ascendant": { "longitude": 249.97, "sign": "Sagittarius", "degInSign": 9.97, "gateLine": { "gate": 9, "line": 5 } }, "descendant": { "sign": "Gemini", "…": "…" }, "mc": { "sign": "Virgo", "…": "…" }, "ic": { "sign": "Pisces", "…": "…" } }, "houses": { "system": "placidus", "cusps": [ { "house": 1, "longitude": 249.97, "sign": "Sagittarius" }, "…" ] } } }