Human Design API: costruire applicazioni HD con 12 endpoint

🕓 Aggiornamento del 2026-04-14, aggiornato il 2026-05-09. Gli SDK TS / Python / PHP ora vivono nei registri pubblici - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). I dettagli sono disponibili in changelog.

Il Design Umano è cresciuto da un sistema esoterico di nicchia degli anni ‘90 a una cornice mainstream di sviluppo personale. Le app con milioni di utenti lo hanno normalizzato - e gli sviluppatori si chiedono: come calcolare la carta del Design Umano in modo programmatico?

In questo post, esploreremo il lato tecnico: cosa sono i calcoli del Design Umano, quali API li supportano e come integrare la funzionalità del Design Umano nella tua app.

Il Design Umano si basa su tre sistemi classici:

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

I calcoli prendono i dati di nascita e producono un bodygraph - una mappa visiva con:

• Tipo (Manifestor, Generatore, Generatore Manifestante, Proiettore, Riflettore) - firma energetica
• Strategia - come prendere decisioni
• Autorità - a quale centro affidarsi nelle decisioni (Sacrale, Emotivo, Splenico, ecc.)
• Profilo - combinazione di linee (1/3, 4/6, ecc.)
• Canali - collegamenti tra i centri che formano la personalità
• Incarnazione Cross - scopo della vita, derivato da quattro posizioni chiave

Sotto il cofano, ogni porta corrisponde a un intervallo di longitudine eclittica. La longitudine dei pianeti al momento della nascita viene mappata su porte specifiche (e righe all’interno di esse). Il calcolo del “Design” - per lo spostamento del Sole di 88° prima della nascita - è di circa 3 mesi prima.

Il Design Umano utilizza due punti di nascita:

1. Personalità - il tempo di nascita reale. Questo è il lato “cosciente”.
2. Design - quando il Sole era a 88° prima della posizione di nascita. Questo è il lato “inconscio”.

Ogni attivazione della porta appartiene a uno di essi. La carta completa ha 13 + 13 = 26 attivazioni.

È proprio questo che rende i calcoli del Design Umano più difficili rispetto alla carta astrologica standard - stai effettivamente calcolando due carte.

La maggior parte delle API di astrologia non supporta il Design Umano o ha un supporto superficiale (solo tipo + strategia). Una implementazione completa del Design Umano richiede:

• Mappatura delle 64 porte (tabella di lookup)
• 6 linee per ogni porta (384 celle)
• 9 centri con logica definita/aperta
• 36 canali (ognuno collega due centri)
• Calcolo dell’Incarnazione Cross
• Estrazione del Profilo dalle linee della porta del Sole + linea della porta della Terra (Personalità e Design)

Le API che possono fare tutto ciò sono rare. AstroWay API ha 12 endpoint del Design Umano - la copertura più approfondita che abbiamo visto in un’API commerciale.

Immagina di aggiungere il Design Umano a un’app di astrologia esistente. Inizia con l’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}`);         // наприклад, "Generator"
console.log(`Strategy: ${hd.strategy}`); // наприклад, "To Respond"
console.log(`Authority: ${hd.authority}`); // наприклад, "Sacral"
console.log(`Profile: ${hd.profile.profile}`);   // наприклад, "1/3"
console.log(`Defined channels: ${hd.channels.length}`);

La 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 - tecnica per comprendere la dinamica di squadra in gruppi di 3-5 persone. È una rarità - la maggior parte dei calcolatori del Design Umano non la offre. Ma è oro per le piattaforme HR-tech, di coaching e 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 del Design Umano sono sensibili all’ora di nascita. Un errore di 10 minuti può cambiare il Profilo (ad esempio, 1/3 → 1/4). Per gli utenti che non conoscono l’ora esatta, esegui l’analisi della sensibilità:

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

// sensitivity покаже, які поля зміняться при зсуві часу на ±5/15/30 хв

Usa questo per avvertire l’utente: “A questa precisione, il tuo profilo potrebbe spostarsi. Considera la rettificazione”.

Se stai costruendo un’app focalizzata sul Design Umano:

• Utente base: 1 carta del Design Umano alla registrazione, memorizzata per sempre = 50 crediti una tantum
• Utente attivo: trasiti periodici + compatibilità = ~200 crediti/mese
• 100 DAU con utilizzo moderato del Design Umano: ~110 000 crediti/mese → Starter ($19/mese) copre facilmente
• 1 000 DAU: ~150 000 crediti/mese → Pro ($59/mese)

Le richieste di compatibilità sono le più pesanti (100 crediti). Memorizza i risultati per ogni coppia di utenti per sempre (non cambiano).

La renderizzazione del bodygraph si esegue tradizionalmente attraverso SVG. L’API restituisce i dati sui centri e i canali; tu renderizzi la visualizzazione. 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 modello fisso (ogni bodygraph ha gli stessi 9 centri e 64 porte nelle stesse posizioni).

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