AstroWay/api v2.102.11 · vi
tất cả hệ thống hoạt động bình thường

Hướng dẫn xây dựng ứng dụng chiêm tinh: hướng dẫn toàn diện cho nhà phát triển

Hướng dẫn từng bước để tạo ứng dụng chiêm tinh từ đầu - chọn API, kiến trúc, bản đồ sao đầu tiên, thêm synastry và chuyển động, triển khai.

🕓 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.

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).

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).

Đừ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.

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

Tạ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:

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

Kiểm tra bằng 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}'

Bạn sẽ nhận được biểu đồ natal đầy đủ dưới dạng JSON.

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>
);
}

Độ 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.

Để 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ó.

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ấ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:

Terminal window
# 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.

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) × 30

Vớ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).

Những tính năng nâng cao đáng để thêm khi ứng dụng phát triển:

  • Overlay transit/v1/transits hiển thị vị trí hiện tại của các hành tinh trên biểu đồ natal
  • Progressions/v1/progressions cho 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 DesignHuman Design API mở ra một lĩnh vực chức năng hoàn toàn mới
  • Astrocartography/v1/acg vẽ 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.

AstroWay team

Đội ngũ kỹ thuật AstroWay API. Chúng tôi đóng gói Swiss Ephemeris thành REST sạch và viết về những chi tiết nhàm chán nhưng quan trọng.

// xây dựng trên nền tảng này

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.

Thêm từ blog tất cả bài viết →

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.