🕓 작성일 2026-04-14, 최종 수정 2026-05-09. TS / Python / PHP SDK는 이제 공개 레지스트리에서 관리됩니다 —
@astroway/sdk(npm),astroway(PyPI),astroway/sdk(Packagist). 자세한 내용은 changelog를 참고하세요.
아스트로 웨이(AstroWay) API로 astrology 앱을 만들고 싶나요? 이 가이드에서는 API 선택부터 실제 제품 배포까지, 필요한 모든 솔루션과 코드를 제공합니다.
아키텍처 선택
섹션 제목: “아키텍처 선택”코드를 작성하기 전에 클라이언트에서 계산할지 서버에서 계산할지 결정하세요.
클라이언트 (예: 브라우저에서 Swiss Ephemeris WASM 사용):
- 장점: 요청당 비용 없음, 오프라인 동작, 완전한 제어
- 단점: 사용자당 ~2MB WASM, Swiss Ephemeris의 복잡한 라이선스(상업적 사용 시 제한), 계산 코드 직접 관리
서버 API (AstroWay, Prokerala 등):
- 장점: 클라이언트 의존성 없음, 앱 번들 크기 감소, 모바일에서 빠른 응답, 라이선스 문제 없음
- 단점: 요청당 크레딧 비용, “콜드 스타트” 지연
대부분의 앱에서는 서버 API가 더 유리합니다. 모바일 사용자는 2MB WASM을 기다리지 않아도 되고, 라이선스 문제도 없으며, 현대적인 API는 동일한 요청을 무료로 캐시합니다(AstroWay는 5분 캐시와 X-Cache: HIT 헤더를 제공합니다).
API 선택 기준
섹션 제목: “API 선택 기준”중요한 요소:
- 정확성 — Swiss Ephemeris가 “아래에서 동작”하는지 확인하세요(±1 각도 초). 명시되지 않았다면 문의하세요.
- 커버리지 — natal + synastry + transit은 기본입니다. progressed aspect와 return은 다음 단계입니다. 희귀한 기술(Rectification, Human Design)은 차별화 요소입니다.
- SDK 품질 — 타입스크립트(TypeScript)와 Python SDK가 시간을 절약해 줍니다.
- 요금 모델 — credit-based 모델이 mixed workload에서 per-request 모델보다 확장성이 뛰어납니다.
이 튜토리얼에서는 AstroWay API를 사용합니다. Swiss Ephemeris 기반, 타입스크립트/파이썬 SDK, credit-based 요금제를 제공하기 때문입니다.
단계 1: 백엔드 설정
섹션 제목: “단계 1: 백엔드 설정”브라우저에서 AstroWay API를 직접 호출하지 마세요 — API 키가 노출됩니다. 항상 백엔드를 통해 호출하세요.
mkdir my-astrology-appcd my-astrology-appnpm init -ynpm install express @astroway/sdk zodnpm install -D typescript @types/express @types/node tsxsrc/server.ts 생성:
import express from 'express';import { Astroway } from '@astroway/sdk';import { z } from 'zod';
const app = express();app.use(express.json());
const client = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY!,});
const BirthInput = z.object({ date: z.string(), time: z.string(), timezoneOffset: z.number(), latitude: z.number(), longitude: z.number(),});
app.post('/api/chart', async (req, res) => { const parsed = BirthInput.safeParse(req.body); if (!parsed.success) return res.status(400).json({ error: parsed.error });
try { const chart = await client.chart({ ...parsed.data, houseSystem: 'P', }); res.json(chart); } catch (err) { res.status(500).json({ error: String(err) }); }});
app.listen(3000, () => console.log('http://localhost:3000'));실행:
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.tscurl로 확인:
curl -X POST http://localhost:3000/api/chart \ -H "Content-Type: application/json" \ -d '{"date":"1990-07-14","time":"14:30:00","timezoneOffset":3,"latitude":50.4501,"longitude":30.5234}'natal chart 전체 JSON을 받게 됩니다.
단계 2: 프론트엔드
섹션 제목: “단계 2: 프론트엔드”어떤 프레임워크든 상관없습니다. 예제로 React와 간단한 폼을 사용해 보겠습니다:
import { useState } from 'react';
type Chart = { planets: { name: string; longitude: number; sign: string; house: number }[]; aspects: { planet1: string; planet2: string; type: string; orb: number }[];};
export function NatalForm() { const [chart, setChart] = useState<Chart | null>(null);
async function handleSubmit(formData: FormData) { const body = Object.fromEntries(formData.entries()); const res = await fetch('/api/chart', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ date: body.date, time: body.time + ':00', timezoneOffset: Number(body.tz), latitude: Number(body.lat), longitude: Number(body.lng), }), }); setChart(await res.json()); }
return ( <div> <form action={handleSubmit}> <input name="date" type="date" required /> <input name="time" type="time" required /> <input name="tz" type="number" placeholder="Timezone offset (예: 3)" required /> <input name="lat" type="number" step="0.0001" placeholder="위도" required /> <input name="lng" type="number" step="0.0001" placeholder="경도" required /> <button>차트 생성</button> </form>
{chart && ( <div> <h2>행성</h2> <ul> {chart.planets.map(p => ( <li key={p.name}>{p.name}: {p.sign} (하우스 {p.house})</li> ))} </ul> <h2>Aspects</h2> <ul> {chart.aspects.map((a, i) => ( <li key={i}>{a.planet1} {a.type} {a.planet2} (orb {a.orb.toFixed(2)}°)</li> ))} </ul> </div> )} </div> );}단계 3: Synastry(시너지)
섹션 제목: “단계 3: Synastry(시너지)”호환성은 다음으로 떠오르는 기능입니다. src/server.ts에 추가하세요:
const SynastryInput = z.object({ chart1: BirthInput, chart2: BirthInput,});
app.post('/api/synastry', async (req, res) => { const parsed = SynastryInput.safeParse(req.body); if (!parsed.success) return res.status(400).json({ error: parsed.error });
const result = await client.synastry(parsed.data); res.json({ score: result.compatibility.score, label: result.compatibility.label, aspects: result.crossAspects, });});완료되었습니다. 하나의 엔드포인트, 호출당 50크레딧, 0–100점의 점수와 cross-aspects를 반환합니다.
단계 4: 일일 호로스코프
섹션 제목: “단계 4: 일일 호로스코프”컨텐츠 engagement를 위해 일일 호로스코프는 필수입니다. AstroWay는 실제 transit 데이터를 기반으로 생성합니다:
app.post('/api/horoscope/daily', async (req, res) => { const parsed = BirthInput.safeParse(req.body); if (!parsed.success) return res.status(400).json({ error: parsed.error });
const horoscope = await client.horoscopeDaily(parsed.data); res.json({ text: horoscope.text, disclaimer: horoscope.disclaimer, // UI에 반드시 표시해야 합니다! });});중요: AI 생성 콘텐츠에는 Terms of Service에 따라 사용자에게 반드시 표시해야 하는 disclaimer가 포함되어 있습니다. 삭제하지 마세요.
단계 5: 캐싱
섹션 제목: “단계 5: 캐싱”일일 호로스코프는 동일한 생년월일과 유사한 natal chart를 가진 모든 사용자에게 동일합니다. 적극적으로 캐시하세요:
import { LRUCache } from 'lru-cache';
const cache = new LRUCache<string, any>({ max: 1000, ttl: 86400 * 1000 });
app.post('/api/horoscope/daily', async (req, res) => { const key = JSON.stringify(req.body); const cached = cache.get(key); if (cached) return res.json(cached);
const horoscope = await client.horoscopeDaily(req.body); cache.set(key, horoscope); res.json(horoscope);});AstroWay에도 5분 서버 측 캐시(X-Cache: HIT)가 있지만, 장기간 캐시가 필요한 콘텐츠는 자체 캐시가 필요합니다.
단계 6: 배포
섹션 제목: “단계 6: 배포”어떤 플랫폼이든 상관없습니다. 빠르게 시작하려면 Vercel 또는 Railway를 추천합니다:
# vercel.json{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }플랫폼 대시보드에서 ASTROWAY_API_KEY 환경 변수를 설정하세요.
예산 계획
섹션 제목: “예산 계획”여기까지 왔다면 배포 전 월간 크레딧 소모량을 추정하세요:
credits/month = DAU × (avg_charts_per_user × 20 + avg_synastries × 50 + avg_horoscopes × 20) × 30일일 1차트 + 1호로스코프 + 0.3시너지 사용자 100명 기준:
100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits / month이는 Starter 플랜으로 $19/월(200K 크레딧)에 해당합니다.
다음 단계
섹션 제목: “다음 단계”앱이 성장하면 추가할 수 있는 고급 기능:
- Overlay Transit —
/v1/transits는 natal chart 위의 현재 행성 위치를 보여줍니다 - Progressed Aspects —
/v1/progressions는 심리적 성장 궤적을 위한 progressed chart입니다 - Solar Return —
/v1/solar-return은 “생일 이후 1년 예측”입니다 - Human Design — Human Design API는 완전히 새로운 기능 영역을 엽니다
- AstroCartography —
/v1/acg는 사용자에게 어디에 살면 좋은지 매핑합니다
모든 기능은 AstroWay API의 단일 호출로 구현할 수 있습니다.
시작하기
섹션 제목: “시작하기”- 무료 API 키 받기 — 월 10,000크레딧
- 전체 API 레퍼런스 — 모든 723 엔드포인트
- Birth Chart API — 차트 엔드포인트 상세 문서
Solar Fire에 사용된 것과 동일한 Swiss Ephemeris — 단 4줄의 코드로.
카드 없이 무료 키. 첫 결제 전까지 월 5,000 API 호출.