AstroWay/api v2.102.11 · ko
모든 시스템 정상 작동 중

아스트로로지 애플리케이션 구축 가이드: 개발자를 위한 완전한 가이드

아스트로로지 애플리케이션을 처음부터 만드는 단계별 가이드 - API 선택, 아키텍처, 첫 번째 내태아 도표, 시나스트리 및 트랜짓 추가, 배포

🕓 작성일 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 헤더를 제공합니다).

중요한 요소:

  • 정확성 — 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 요금제를 제공하기 때문입니다.

브라우저에서 AstroWay API를 직접 호출하지 마세요 — API 키가 노출됩니다. 항상 백엔드를 통해 호출하세요.

Terminal window
mkdir my-astrology-app
cd my-astrology-app
npm init -y
npm install express @astroway/sdk zod
npm install -D typescript @types/express @types/node tsx

src/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'));

실행:

Terminal window
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.ts

curl로 확인:

Terminal window
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을 받게 됩니다.

어떤 프레임워크든 상관없습니다. 예제로 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>
);
}

호환성은 다음으로 떠오르는 기능입니다. 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를 반환합니다.

컨텐츠 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가 포함되어 있습니다. 삭제하지 마세요.

일일 호로스코프는 동일한 생년월일과 유사한 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)가 있지만, 장기간 캐시가 필요한 콘텐츠는 자체 캐시가 필요합니다.

어떤 플랫폼이든 상관없습니다. 빠르게 시작하려면 Vercel 또는 Railway를 추천합니다:

Terminal window
# 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 DesignHuman Design API는 완전히 새로운 기능 영역을 엽니다
  • AstroCartography/v1/acg는 사용자에게 어디에 살면 좋은지 매핑합니다

모든 기능은 AstroWay API의 단일 호출로 구현할 수 있습니다.

AstroWay team

AstroWay API 엔지니어링 팀. Swiss Ephemeris를 깔끔한 REST로 감싸고, 사실상 중요한 지루한 세부 사항들을 다룹니다.

// 이걸로 빌드해

Solar Fire에 사용된 것과 동일한 Swiss Ephemeris — 단 4줄의 코드로.

카드 없이 무료 키. 첫 결제 전까지 월 5,000 API 호출.

더 많은 블로그 글 모든 글 보기 →

Engineering 2026-06-05

Natal Chart API in TypeScript: SDK + React Example

Compute a natal chart in TypeScript with the AstroWay SDK — typed responses, a React component, and where it beats a local ephemeris library.

Ephemeris 2026-06-05

How Accurate Is the Swiss Ephemeris? Verified Benchmarks

Swiss Ephemeris accuracy in numbers — planetary positions under 0.1 arcsecond, exact house cusps, eclipses within a minute — and how AstroWay verifies it.

Ephemeris 2026-06-05

Swiss Ephemeris: REST API vs pyswisseph (When to Use Which)

pyswisseph vs a REST API for Swiss Ephemeris calculations — C dependencies, data files, licensing and deployment compared, with a decision guide.