🕓 2026年4月14日の記録、2026年5月9日に更新。 TS / Python / PHP SDK はそれぞれ
@astroway/sdk(npm)、astroway(PyPI)、astroway/sdk(Packagist) で公開レジストリに移行しました。詳細は changelog をご覧ください。
アストロロジーアプリを作りたいと思っている?このガイドでは、APIの選択から実用的なプロダクトのデプロイまで、解決策とコードを紹介します。
アーキテクチャの検討
Section titled “アーキテクチャの検討”コードを書く前に、計算をクライアント側で行うか、サーバー側で行うかを決めよう。
クライアント側(例:ブラウザ上で動作するSwiss Ephemeris WASM):
- メリット:リクエストごとのコストがかからない、オフラインで動作、計算コードを完全に制御可能
- デメリット:各ユーザーにつき約2MBのWASMが必要、商用利用時のSwiss Ephemerisのライセンス制限、計算コードのメンテナンスが必要
サーバー側API(AstroWay、Prokeralaなど):
- メリット:クライアント側の依存関係が不要、アプリのバンドルサイズが小さい、モバイルで高速、ライセンスの煩わしさがない
- デメリット:リクエストごとのクレジットコスト、初回リクエスト時のレイテンシ
ほとんどのアプリケーションでは、サーバー側APIの方が有利です。モバイルユーザーは2MBのWASMを待ちたくないし、ライセンスの問題に悩まされたくない。その上、現代のAPIは同一リクエストを無料でキャッシュしてくれる(AstroWayでは5分間のキャッシュがX-Cache: HITというヘッダーで提供されている)。
APIの選択
Section titled “APIの選択”重要なポイント:
- 精度 — Swiss Ephemerisが「裏で」使われているか(±1秒角)。明記されていない場合は確認しよう。
- カバレッジ — ナタルチャート + シナストリー + トランジットが最低限。プログレッションやリターンは次のレベル。レアなテクニック(レクティフィケーション、ヒューマンデザイン)は差別化要因。
- SDKの品質 — TypeScriptやPythonの型付きSDKは何時間もの節約になる。
- 料金モデル — クレジットベースの方が、リクエスト単位の料金よりも混合負荷に対してスケールしやすい。
このチュートリアルでは、AstroWay API を使う。なぜなら、4つの条件(723エンドポイント、Swiss Ephemeris、型付きSDK、クレジットベース)をすべて満たしているからだ。
ステップ1:バックエンドのセットアップ
Section titled “ステップ1:バックエンドのセットアップ”アストロロジーAPIを直接ブラウザから呼び出すのはNG — 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}'これで完全なJSON形式のナタルチャートが手に入る。
ステップ2:フロントエンド
Section titled “ステップ2:フロントエンド”どんなフレームワークでもOK。例として、シンプルなフォームを使った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>アスペクト</h2> <ul> {chart.aspects.map((a, i) => ( <li key={i}>{a.planet1} {a.type} {a.planet2} (オーブ{a.orb.toFixed(2)}°)</li> ))} </ul> </div> )} </div> );}ステップ3:シナストリー
Section titled “ステップ3:シナストリー”互換性は次の明らかな機能だ。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, });});これで完了。1エンドポイント、リクエストごとに50クレジットで、スコア0–100とクロスアスペクトを返す。
ステップ4:デイリーホロスコープ
Section titled “ステップ4:デイリーホロスコープ”コンテンツエンゲージメントのためにデイリーホロスコープは必須だ。AstroWayはリアルなトランジットデータから生成してくれる:
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で生成されたコンテンツには必ずdisclaimerが含まれており、利用規約でユーザーに表示することが義務付けられている。削除しないように。
ステップ5:キャッシュ
Section titled “ステップ5:キャッシュ”デイリーホロスコープは、同じ誕生日で似たようなナタルチャートを持つユーザーにとっては毎日同じ内容になる。積極的にキャッシュしよう:
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:デプロイ
Section titled “ステップ6:デプロイ”どんなプラットフォームでもOK。手早く始めるなら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) × 301日あたり1チャート + 1ホロスコープ + 0.3シナストリーを平均ユーザーが利用する100DAUの場合:
100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 credits / monthこれはStarterプランで月額$19(200Kクレジット)だ。
次にやること
Section titled “次にやること”成長に合わせて追加したい高度な機能:
- トランジットオーバーレイ —
/v1/transitsで現在の惑星位置をナタルチャート上に表示 - プログレッション —
/v1/progressionsで心理的発達のアークを表示 - ソーラーリターン —
/v1/solar-returnで「誕生日から1年後の予測」を表示 - ヒューマンデザイン — Human Design APIでまったく新しい機能領域を開拓
- アストロカルトログラフィー —
/v1/acgでユーザーに最適な居住地をマッピング
どの機能もゼロから実装するのは大変だが、AstroWayのAPIを使えば1回のリクエストで済む。
スタートしよう
Section titled “スタートしよう”- 無料のAPIキーを取得 — 月間10,000クレジット
- 完全なAPIリファレンス — すべての723エンドポイント
- Birth Chart API — チャートエンドポイントの詳細ドキュメント
Solar Fireと同じSwiss Ephemeris — 4行のコードで。
無料のキー(カード不要)。最初の支払いまでに月5,000回の呼び出し。