인생그래프 API

외부 연동 실무 가이드 · v1.0.1

← 웹앱으로

이 문서 하나로 다른 사이트·앱·프로그램에서 인생그래프 계산 결과를 받아갈 수 있도록 등록 → 연결 → 결제 → 검증 순서로 설명합니다.

1. 등록방법 2. API 연결방법 3. 응답 구조 4. 결제방법 5. 검증용 API 6. 이용 수칙

1. 등록방법 (API 키 발급)

  1. 웹앱 우측 상단에서 회원가입 / 로그인합니다.
  2. 아래 API 키 관리에서 키를 발급받습니다. 키 전체 값은 발급 순간 한 번만 표시되므로 안전한 곳에 보관하세요.
  3. 모든 요청 헤더에 X-API-Key: 발급받은키 를 넣어 호출합니다.
현재는 개발 단계라 키 없이도 호출이 허용되지만, 정식 오픈 시 키 없는 호출은 차단됩니다. 연동 개발 시점부터 키를 붙여 두세요. 잘못된 키를 보내면 401이 반환됩니다.
API 키 관리
키 발급은 로그인 후 가능합니다. 웹앱에서 로그인 한 뒤 이 페이지를 새로고침하세요.

2. API 연결방법

기본 주소: https://insengflow.com · 모든 계산 요청은 POST + JSON 입니다. 시각은 시간대 표기가 없는 현지 표준시(예: 1990-03-15T08:20:00)로 보냅니다.

엔드포인트용도필수 입력
POST /point한 시점 계산t, location
POST /timeseries/seventy-years년간(0~70세) 시계열location, person_a
POST /timeseries/one-year1년(월 단위) 시계열location, year
POST /timeseries/one-month1개월(일 단위)location, year, month
POST /timeseries/one-day1일(시 단위)location, year, month, day
GET /locations등록 위치 목록-
GET /relations궁합 관계 이름 목록-
GET /palette그래프 표시용 색상-

공통 입력 필드

필드설명
location분석 위치. 등록 이름 {"name":"서울"} 또는 임의 좌표 {"country":"...","tz_ref_longitude":135,"latitude":37.5,"longitude":127}
person_a, person_b사주정보. {"name":"홍길동","sex":"남","birth":"1990-03-15T08:20","location":{"name":"부산"}}. 둘 다 없으면 현재분석, A만 있으면 개인분석, A+B면 궁합분석.
relation궁합 관계. GET /relations가 주는 이름 중 하나를 그대로 보냅니다.

호출 예제 — 한 시점 계산 (curl)

curl -X POST https://insengflow.com/point \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sjk_발급받은키" \
  -d '{
    "t": "2026-07-05T14:30:00",
    "location": {"name": "서울"},
    "person_a": {"name": "홍길동", "sex": "남",
                 "birth": "1990-03-15T08:20", "location": {"name": "부산"}}
  }'

호출 예제 — 1년 시계열 (JavaScript)

const res = await fetch('https://insengflow.com/timeseries/one-year', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json',
             'X-API-Key': 'sjk_발급받은키' },
  body: JSON.stringify({
    location: { name: '서울' }, year: 2026,
    person_a: { name: '홍길동', sex: '남',
                birth: '1990-03-15T08:20', location: { name: '부산' } },
  }),
});
const data = await res.json();
// data.subjects[0].points → 그래프 포인트 배열

호출 예제 — 궁합 (Python)

import requests

r = requests.post(
    "https://insengflow.com/timeseries/one-day",
    headers={"X-API-Key": "sjk_발급받은키"},
    json={
        "location": {"name": "서울"},
        "year": 2026, "month": 7, "day": 5,
        "person_a": {"name": "A", "sex": "남",
                     "birth": "1990-03-15T08:20", "location": {"name": "부산"}},
        "person_b": {"name": "B", "sex": "여",
                     "birth": "1992-11-02T23:10", "location": {"name": "서울"}},
        "relation": "연인",
    })
data = r.json()   # subjects 2개 (A, B)

3. 응답 구조 (무엇을 받게 되나)

시계열 응답의 뼈대:

{
  "뷰": "1년", "x단위": "월",
  "subjects": [
    { "대상": "홍길동",
      "points": [ { ...한 시점의 표시값... }, ... ] }
  ]
}

포인트 하나의 표시값 (§11 결과 구조):

키내용
시계시각이 포인트의 시계시간 (표시용은 반드시 이 값 사용)
본원{"표기":"갑∞","무한":true,"경로":[...]} — 십성 기준 천간
충전_십간 / 충후_십간충 적용 전/후 십간 10개의 수치
충전_십성 / 충후_십성충 적용 전/후 십성 10개의 수치 (비견~정인)
단일곡선종합 평가 곡선 값 1개
변운소스별 변운 [{"소스":"현운년","간지":"병오","변운":"병기"}, ...]
메타뷰에 따라 년도/나이/월/일/시/절기/시기

그래프를 그린다면: x축 = 시계시각, y축 = 원하는 시리즈 (충전_십성.비견 등), 색상은 GET /palette를 그대로 쓰면 웹앱과 동일한 표준 색이 됩니다.

오류 코드

코드의미
401API 키가 잘못됨 (키 재확인)
404등록되지 않은 위치 이름
422입력값 오류 — 응답의 detail에 원인 (예: 존재하지 않는 날짜, 알 수 없는 관계)
500서버 내부 오류 — 상세는 노출되지 않으며 재시도 후 문의

4. 결제방법

포인트 기반 과금(§15)을 준비 중입니다. 예정 구조:

5. 검증용 API 페이지 (Swagger)

모든 엔드포인트를 브라우저에서 직접 실험할 수 있는 검증용 문서:

→ 검증용 API 콘솔 열기 (Swagger UI)

각 엔드포인트의 Try it out으로 요청을 보내 실제 응답을 확인할 수 있습니다. 스키마(입력 형식)도 여기서 확인하세요.

6. 이용 수칙

API 응답에는 3장에 설명된 결과 표시값만 포함됩니다.