🕓 Bài viết từ 2026-04-14, cập nhật 2026-05-09. TS / Python / PHP SDK giờ đây đã có sẵn trên các kho công khai —
@astroway/sdk(npm),astroway(PyPI),astroway/sdk(Packagist). Chi tiết xem trong changelog.
Bạn muốn xây dựng một ứng dụng chiêm tinh? Bắt đầu từ đâu? Hướng dẫn này sẽ cung cấp giải pháp và mã nguồn: từ việc chọn API đến triển khai sản phẩm hoạt động.
Câu hỏi về kiến trúc
Phần tiêu đề “Câu hỏi về kiến trúc”Trước khi viết code, hãy quyết định: tính toán trên client hay server?
Client (ví dụ: Swiss Ephemeris WASM trong trình duyệt):
- Ưu điểm: không tốn phí cho mỗi yêu cầu, hoạt động offline, toàn quyền kiểm soát
- Nhược điểm: ~2 MB WASM cho mỗi người dùng, giấy phép phức tạp (sử dụng thương mại Swiss Ephemeris bị hạn chế), bạn phải tự quản lý code tính toán
API Server (AstroWay, Prokerala, v.v.):
- Ưu điểm: không phụ thuộc vào client, dung lượng ứng dụng nhỏ, nhanh trên mobile, không lo vấn đề giấy phép
- Nhược điểm: tốn phí theo tín dụng cho mỗi yêu cầu, độ trễ trên các yêu cầu “lạnh”
Đối với hầu hết ứng dụng, API server sẽ là lựa chọn tốt hơn. Người dùng mobile không muốn chờ tải 2 MB WASM; bạn cũng không cần phải đối mặt với những rắc rối về giấy phép; và các API hiện đại thường miễn phí cache các yêu cầu giống nhau (AstroWay cung cấp cache 5 phút với header X-Cache: HIT).
Chọn API
Phần tiêu đề “Chọn API”Những yếu tố quan trọng:
- Độ chính xác — hãy tìm kiếm Swiss Ephemeris “ẩn dưới mui xe” (±1 giây cung). Nếu API không đề cập trực tiếp, hãy hỏi họ.
- Phạm vi hỗ trợ — natal + synastry + transit là tối thiểu. Progression và return là mức tiếp theo. Các kỹ thuật hiếm (rectification, Human Design) là điểm khác biệt.
- Chất lượng SDK — SDK TypeScript và Python đã được gõ kiểu giúp tiết kiệm hàng giờ.
- Mô hình giá — credit-based phù hợp hơn per-request khi tải hỗn hợp.
Trong hướng dẫn này, chúng ta sẽ sử dụng AstroWay API vì nó đáp ứng đủ 4 tiêu chí (723 endpoint, Swiss Ephemeris, SDK đã gõ kiểu, credit-based).
Bước 1: Thiết lập backend
Phần tiêu đề “Bước 1: Thiết lập backend”Đừng bao giờ gọi API chiêm tinh trực tiếp từ trình duyệt — khóa API của bạn sẽ bị lộ. Luôn luôn thông qua backend của riêng bạn.
mkdir my-astrology-appcd my-astrology-appnpm init -ynpm install express @astroway/sdk zodnpm install -D typescript @types/express @types/node tsxTạo tệp 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'));Chạy:
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.tsKiểm tra bằng curl:
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}'Bạn sẽ nhận được biểu đồ natal đầy đủ dưới dạng JSON.
Bước 2: Frontend
Phần tiêu đề “Bước 2: Frontend”Bất kỳ framework nào cũng phù hợp. Ví dụ dưới đây sử dụng React với form đơn giản:
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="Múi giờ (ví dụ 3)" required /> <input name="lat" type="number" step="0.0001" placeholder="Vĩ độ" required /> <input name="lng" type="number" step="0.0001" placeholder="Kinh độ" required /> <button>Build chart</button> </form>
{chart && ( <div> <h2>Hành tinh</h2> <ul> {chart.planets.map(p => ( <li key={p.name}>{p.name}: {p.sign} (nhà {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> );}Bước 3: Synastry
Phần tiêu đề “Bước 3: Synastry”Độ tương thích là tính năng hiển nhiên tiếp theo. Thêm vào 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, });});Xong. Một endpoint, 50 tín dụng mỗi lần gọi, trả về điểm số 0–100 và cross-aspects.
Bước 4: Horoscope hàng ngày
Phần tiêu đề “Bước 4: Horoscope hàng ngày”Để tăng engagement nội dung, horoscope hàng ngày là điều bắt buộc. AstroWay tạo ra chúng từ dữ liệu transit thực tế:
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, // bắt buộc phải hiển thị trong UI! });});Lưu ý quan trọng: Nội dung do AI tạo ra đều chứa disclaimer mà bạn phải hiển thị cho người dùng (theo Terms of Service). Đừng bỏ qua nó.
Bước 5: Cache
Phần tiêu đề “Bước 5: Cache”Horoscope hàng ngày giống nhau cho tất cả người dùng có cùng ngày sinh và biểu đồ natal tương tự. Hãy cache mạnh mẽ:
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 cũng có cache server 5 phút (X-Cache: HIT), nhưng đối với nội dung tồn tại lâu dài, bạn cần cache riêng.
Bước 6: Triển khai
Phần tiêu đề “Bước 6: Triển khai”Bất kỳ nền tảng nào cũng phù hợp. Để bắt đầu nhanh chóng, bạn có thể dùng Vercel hoặc Railway:
# vercel.json{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }Trên bảng điều khiển nền tảng, thiết lập biến môi trường ASTROWAY_API_KEY.
Lập kế hoạch ngân sách
Phần tiêu đề “Lập kế hoạch ngân sách”Nếu bạn đã đến bước này, hãy ước tính mức tiêu thụ tín dụng hàng tháng trước khi triển khai:
tín dụng/tháng = DAU × (avg_charts_per_user × 20 + avg_synastries × 50 + avg_horoscopes × 20) × 30Với 100 DAU, mỗi người dùng có 1 biểu đồ + 1 horoscope + 0.3 synastry mỗi ngày:
100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 tín dụng / thángĐây là gói Starter với giá $19/tháng (200K tín dụng).
Tiếp theo là gì?
Phần tiêu đề “Tiếp theo là gì?”Những tính năng nâng cao đáng để thêm khi ứng dụng phát triển:
- Overlay transit —
/v1/transitshiển thị vị trí hiện tại của các hành tinh trên biểu đồ natal - Progressions —
/v1/progressionscho sự phát triển tâm lý theo vòng đời - Solar return —
/v1/solar-return“dự đoán cho năm tới kể từ ngày sinh” - Human Design — Human Design API mở ra một lĩnh vực chức năng hoàn toàn mới
- Astrocartography —
/v1/acgvẽ bản đồ nơi người dùng nên sống
Mỗi tính năng đều khó triển khai từ đầu, nhưng chỉ cần một lời gọi API tới AstroWay.
Bắt đầu thôi
Phần tiêu đề “Bắt đầu thôi”- Nhận khóa API miễn phí — 10 000 tín dụng / tháng
- Tài liệu tham khảo API đầy đủ — tất cả 723 endpoint
- Birth Chart API — tài liệu chi tiết về endpoint biểu đồ
Chính Swiss Ephemeris giống như trong Solar Fire — chỉ trong 4 dòng code.
Khóa API miễn phí không cần thẻ. 5.000 lượt gọi/tháng trước lần thanh toán đầu tiên.