Human Design API: 12개 엔드포인트로 HD 앱 만들기

🕓 2026-04-14 작성, 2026-05-09 업데이트. TS / Python / PHP SDK는 이제 public registries에 있습니다 - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). 자세한 내용은 changelog를 참고하세요.

Human Design은 1990년대의 틈새 비전(秘傳) 체계에서 주류 자기계발 프레임워크로 성장했습니다. 수백만 사용자를 가진 앱들이 이를 대중화했고, 개발자들은 이렇게 묻기 시작했습니다: Human Design 차트를 프로그래밍으로 어떻게 계산할까?

이 글은 기술적인 측면을 다룹니다: HD 계산이란 무엇인지, 어떤 API가 이를 지원하는지, 그리고 여러분의 앱에 HD 기능을 어떻게 넣을 수 있는지.

Human Design은 세 가지 고전 체계 위에 세워져 있습니다:

• 서양 점성술: 출생 순간의 행성 위치
• I Ching(주역): 64개 “게이트”에 매핑된 64괘
• 차크라 체계: 9개의 “센터”(에너지 노드)

계산은 출생 데이터를 받아 bodygraph를 만듭니다. 다음을 담은 시각적 차트입니다:

• Type (Manifestor, Generator, Manifesting Generator, Projector, Reflector): 에너지 시그니처
• Strategy: 결정을 내리는 방식
• Authority: 결정할 때 신뢰할 센터 (Sacral, Emotional, Splenic 등)
• Profile: 라인 조합 (1/3, 4/6 등)
• Channels: 성격을 형성하는 센터 간 연결
• Incarnation Cross: 네 개의 핵심 위치에서 도출되는 삶의 목적

내부적으로 64개 게이트는 각각 황경의 한 구간에 대응합니다. 출생 시 행성의 황경이 특정 게이트(그리고 그 안의 라인)에 매핑됩니다. “Design” 계산은 태양이 출생 위치보다 88° 이전에 있던 시점, 즉 대략 3개월 전을 기준으로 합니다.

Human Design은 두 개의 출생 시점을 사용합니다:

1. Personality: 실제 출생 시각. “의식적인” 측면입니다.
2. Design: 태양이 출생 위치보다 88° 이전에 있던 시점. “무의식적인” 측면입니다.

모든 게이트 활성화는 둘 중 하나에 속합니다. 전체 차트에는 13 + 13 = 26개의 활성화가 있습니다.

바로 이 점이 HD 계산을 일반 점성술 차트보다 무겁게 만듭니다. 사실상 차트 두 개를 계산하는 셈이니까요.

대부분의 점성술 API는 HD를 아예 지원하지 않거나 표면적으로만 지원합니다(type + strategy만). 완전한 HD 구현에는 다음이 필요합니다:

• 64개 게이트 매핑 (lookup table)
• 게이트마다 6개 라인 (384칸)
• defined/open 로직을 가진 9개 센터
• 36개 채널 (각각 두 센터를 연결)
• Incarnation Cross 계산
• 태양 게이트 라인 + 지구 게이트 라인(Personality와 Design)에서 Profile 도출

이 모든 것을 해내는 API는 매우 드뭅니다. AstroWay API는 12개의 HD 엔드포인트를 제공합니다. 저희가 상용 API에서 본 것 중 가장 깊은 커버리지입니다.

이미 있는 점성술 앱에 HD를 추가한다고 해 봅시다. 메인 엔드포인트부터 시작하세요:

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}`);

응답 형태:

{
  "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는 3–5명 그룹에서 팀 다이내믹스를 이해하는 기법입니다. 흔하지 않은 기능이라 대부분의 HD 계산기는 제공하지 않습니다. 하지만 HR-tech, 코칭 플랫폼, 팀 빌딩 앱에는 금광과 같습니다.

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}`);

HD 차트는 출생 시각에 민감합니다. 10분 오차만으로도 Profile이 바뀔 수 있습니다(예: 1/3 → 1/4). 정확한 출생 시각을 모르는 사용자에게는 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

이 결과로 사용자에게 경고를 보여 주세요: “이 정확도에서는 profile이 바뀔 수 있습니다. 렉티피케이션(출생 시각 보정)을 고려해 보세요”.

HD 중심 앱을 만든다면:

• 기본 사용자: 가입 시 HD 차트 1개, 영구 캐시 = 1회 50 크레딧
• 활성 사용자: 주기적인 트랜짓 + compatibility = 월 ~200 크레딧
• HD를 적당히 쓰는 DAU 100명: 월 ~110 000 크레딧 → **Starter ($19/월)**로 충분
• DAU 1 000명: 월 ~150 000 크레딧 → Pro ($59/월)

Compatibility 요청이 가장 무겁습니다(100 크레딧). 사용자 쌍마다 결과를 영구히 캐시하세요(결과는 변하지 않습니다).

bodygraph 렌더링은 전통적으로 SVG로 합니다. API는 센터와 채널 데이터를 반환하고, 시각화는 여러분이 렌더링합니다. 예시:

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>
  );
}

좌표는 고정 템플릿입니다(모든 bodygraph는 같은 위치에 같은 9개 센터와 64개 게이트를 가집니다).

• Human Design API: 전체 엔드포인트 목록이 있는 제품 페이지
• 예제: Human Design: /v1/human-design 상세 walkthrough
• 빠른 시작: 무료 API 키 받기 (Free 플랜에서 월 최대 200개 HD 차트)