Human Design API: costruisci app HD su 12 endpoint

🕓 Articolo del 2026-04-14, aggiornato il 2026-05-09. Gli SDK TS / Python / PHP ora sono sui registry pubblici: @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Dettagli nel changelog.

Human Design è passato da sistema esoterico di nicchia degli anni ‘90 a quadro mainstream di crescita personale. App con milioni di utenti lo hanno reso normale, e gli sviluppatori si chiedono: come si calcola una carta di Human Design in modo programmatico?

In questo post parliamo del lato tecnico: cosa sono i calcoli HD, quali API li supportano e come integrare una funzione HD nella tua app.

Human Design si basa su tre sistemi classici:

• Astrologia occidentale: le posizioni dei pianeti al momento della nascita
• I Ching: 64 esagrammi mappati su 64 “porte”
• Sistema dei chakra: nove “centri” (nodi energetici)

Il calcolo prende i dati di nascita e produce un bodygraph, una mappa visiva con:

• Type (Manifestor, Generator, Manifesting Generator, Projector, Reflector): la firma energetica
• Strategy: come prendere le decisioni
• Authority: a quale centro affidarsi nelle decisioni (Sacral, Emotional, Splenic e così via)
• Profile: combinazione di linee (1/3, 4/6 e così via)
• Channels: i collegamenti tra centri che formano la personalità
• Incarnation Cross: lo scopo di vita, derivato da quattro posizioni chiave

Sotto il cofano, ciascuna delle 64 porte corrisponde a un intervallo di longitudine eclittica. La longitudine dei tuoi pianeti alla nascita viene mappata su porte precise (e sulle linee al loro interno). Il calcolo del “Design” riguarda lo spostamento del Sole di 88° prima della nascita, circa 3 mesi prima.

Human Design usa due momenti di nascita:

1. Personality: l’ora reale di nascita. È il lato “conscio”.
2. Design: quando il Sole si trovava 88° prima della posizione di nascita. È il lato “inconscio”.

Ogni attivazione di porta appartiene a uno dei due. Una carta completa ha 13 + 13 = 26 attivazioni.

È proprio questo che rende il calcolo HD più pesante di una carta astrologica standard: in pratica calcoli due carte.

La maggior parte delle API di astrologia non supporta HD affatto, oppure lo supporta in modo superficiale (solo type + strategy). Un’implementazione HD completa richiede:

• La mappatura delle 64 porte (lookup table)
• 6 linee per ogni porta (384 celle)
• 9 centri con la logica defined/open
• 36 canali (ognuno collega due centri)
• Il calcolo dell’Incarnation Cross
• La derivazione del Profile dalla linea della porta del Sole + la linea della porta della Terra (Personality e Design)

Le API che sanno fare tutto questo sono una vera rarità. L’API di AstroWay ha 12 endpoint HD, la copertura più profonda che abbiamo visto in un’API commerciale.

Immagina di aggiungere HD a un’app di astrologia già esistente. Parti dall’endpoint principale:

import { Astroway } from '@astroway/sdk';

const client = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const hd = await client.humanDesign.compute({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,
  latitude: 50.4501,
  longitude: 30.5234,
});

console.log(`Type: ${hd.type}`);         // e.g. "Generator"
console.log(`Strategy: ${hd.strategy}`); // e.g. "To Respond"
console.log(`Authority: ${hd.authority}`); // e.g. "Sacral"
console.log(`Profile: ${hd.profile.profile}`);   // e.g. "1/3"
console.log(`Defined channels: ${hd.channels.length}`);

Forma della risposta:

{
  "type": "Generator",
  "strategy": "To Respond",
  "notSelfTheme": "Frustration",
  "authority": "Sacral",
  "profile": "1/3",
  "definition": "single",
  "cross": {
    "name": "Right Angle Cross of the Sphinx",
    "quarter": "Civilization",
    "gates": [1, 2, 7, 13]
  },
  "centers": [
    { "name": "Sacral", "defined": true },
    ...
  ],
  "channels": [
    { "gate1": 34, "gate2": 20, "name": "Channel of Charisma", "type": "Generated" }
  ],
  "personalityActivations": [...],
  "designActivations": [...]
}

Penta è una tecnica per capire le dinamiche di squadra in gruppi di 3–5 persone. È una rarità: quasi nessun calcolatore HD la offre. Ma è oro per HR-tech, piattaforme di coaching e app di team building.

const penta = await client.hd.penta({
  inputs: [
    { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
    { date: '1988-03-10', time: '08:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
    { date: '1985-11-22', time: '18:00:00', timezoneOffset: -5, latitude: 40.71, longitude: -74.00 },
  ],
});

console.log(`Members: ${penta.memberCount}`);
console.log(`Channels in the group: ${penta.channels.length}`);

Le carte HD sono sensibili all’ora di nascita. Un errore di 10 minuti può cambiare il Profile (ad esempio 1/3 → 1/4). Per gli utenti che non conoscono l’ora esatta, lancia l’analisi di sensitivity:

const sensitivity = await client.hd.sensitivity({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,
  latitude: 50.4501,
  longitude: 30.5234,
});

// sensitivity tells you which fields change if time shifts ±5/15/30 min

Usala per avvisare l’utente: “Con questa precisione il tuo profile potrebbe spostarsi. Valuta una rettifica”.

Se stai costruendo un’app centrata su HD:

• Utente base: 1 carta HD alla registrazione, in cache per sempre = 50 crediti una tantum
• Utente attivo: transiti periodici + compatibility = ~200 crediti/mese
• 100 DAU con un uso moderato di HD: ~110 000 crediti/mese → Starter ($19/mese) li copre senza problemi
• 1 000 DAU: ~150 000 crediti/mese → Pro ($59/mese)

Le richieste di compatibility sono le più pesanti (100 crediti). Salva in cache i risultati di ogni coppia di utenti per sempre (non cambiano).

Il bodygraph si renderizza tradizionalmente in SVG. L’API restituisce i dati su centri e canali, tu renderizzi la parte visiva. Esempio:

function Bodygraph({ hd }: { hd: HDChart }) {
  return (
    <svg viewBox="0 0 400 600">
      {hd.centers.map(c => (
        <polygon
          key={c.name}
          points={CENTER_COORDS[c.name]}
          fill={c.defined ? CENTER_COLORS[c.name] : 'white'}
          stroke="black"
        />
      ))}
      {hd.channels.map(ch => (
        <line
          key={`${ch.gate1}-${ch.gate2}`}
          x1={GATE_COORDS[ch.gate1].x}
          y1={GATE_COORDS[ch.gate1].y}
          x2={GATE_COORDS[ch.gate2].x}
          y2={GATE_COORDS[ch.gate2].y}
          stroke="#d4a84c"
          strokeWidth="3"
        />
      ))}
    </svg>
  );
}

Le coordinate sono un template fisso (ogni bodygraph ha gli stessi 9 centri e le stesse 64 porte nelle stesse posizioni).

• Human Design API: la pagina prodotto con l’elenco completo degli endpoint
• Esempio: Human Design: walkthrough dettagliato di /v1/human-design
• Guida rapida: ottieni una chiave API gratuita (fino a 200 carte HD/mese sul piano Free)