AstroWay/api v2.295.7 · id
semua sistem normal

Membangun Aplikasi Astrologi: Panduan Lengkap untuk Pengembang

Panduan langkah demi langkah untuk membuat aplikasi astrologi dari awal - memilih API, arsitektur, kartu natal pertama, menambahkan sinastri dan transito, deploy.

🕓 Catatan dari 2026-04-14, diperbarui pada 2026-05-09. TS / Python / PHP SDK sekarang tersedia di public registries - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detailnya ada di changelog.

Mau membuat aplikasi astrologi. Dari mana mulai? Di panduan ini - solusi dan kode: dari memilih API hingga mendeploy produk yang berfungsi.

Sebelum menulis kode, tentukan: perhitungan di klien atau di server?

Klien (misalnya, Swiss Ephemeris WASM di browser):

  • Plus: tidak ada biaya per permintaan, bekerja offline, kontrol penuh
  • Minus: ~2 MB WASM per pengguna, lisensi yang rumit (penggunaan komersial Swiss Ephemeris memiliki batasan), kamu sendiri yang memelihara kode perhitungan

API Server (AstroWay, Prokerala, dll.):

  • Plus: tanpa dependensi klien, bundle aplikasi yang kecil, cepat di mobile, tanpa masalah lisensi
  • Minus: biaya dalam kredit per permintaan, penundaan pada permintaan “dingin”

Untuk sebagian besar aplikasi, API server menang. Pengguna mobile tidak akan menunggu 2 MB WASM; tidak perlu repot dengan nuansa lisensi; dan API modern secara gratis meng-cache permintaan identik (AstroWay melakukan cache 5 menit dengan header X-Cache: HIT).

Yang penting:

  • Akurasi: cari Swiss Ephemeris “di bawah kap” (±1 detik sudut). Jika API tidak secara langsung menyebutkannya - tanyakan.
  • Cakupan: natal + sinastri + transit: minimum. Progresi dan return - tingkat berikutnya. Teknik langka (rectifikasi, Human Design) - ini adalah pembeda.
  • Kualitas SDK: TypeScript dan Python SDK yang ter-tipe menghemat jam kerja.
  • Model tarif: berbasis kredit lebih skalable daripada per-request pada beban campuran.

Untuk tutorial ini, kita akan menggunakan AstroWay API, karena memiliki keempatnya (777 endpoint, Swiss Ephemeris, SDK ter-tipe, berbasis kredit).

Jangan pernah memanggil API astrologi langsung dari browser - kunci API Anda akan bocor. Selalu melalui backend Anda sendiri.

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

Buat 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.compute({
...parsed.data,
houseSystem: 'P',
});
res.json(chart);
} catch (err) {
res.status(500).json({ error: String(err) });
}
});
app.listen(3000, () => console.log('http://localhost:3000'));

Jalankan:

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

Verifikasi dengan 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}'

Anda mendapatkan birth chart JSON lengkap.

Framework apa pun akan cocok. Sebagai contoh - React dengan form sederhana:

import { useState } from 'react';
type Chart = {
planets: { name: string; longitude: number; isRetrograde: boolean }[];
aspects: { planet1: string; planet2: string; type: { name: string }; orb: number }[];
};
// Planets come with ecliptic longitude, not a sign: the sign is that longitude
// divided by 30. Work it out on your side, it is cheaper than another call.
const SIGNS = ['Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces'];
const signOf = (longitude: number) => SIGNS[Math.floor(longitude / 30) % 12];
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 (e.g. 3)" required />
<input name="lat" type="number" step="0.0001" placeholder="Latitude" required />
<input name="lng" type="number" step="0.0001" placeholder="Longitude" required />
<button>Build chart</button>
</form>
{chart && (
<div>
<h2>Planets</h2>
<ul>
{chart.planets.map(p => (
<li key={p.name}>{p.name}: {signOf(p.longitude)} {(p.longitude % 30).toFixed(2)}°{p.isRetrograde ? ' R' : ''}</li>
))}
</ul>
<h2>Aspects</h2>
<ul>
{chart.aspects.map((a, i) => (
<li key={i}>{a.planet1} {a.type.name} {a.planet2} (orb {a.orb.toFixed(2)}°)</li>
))}
</ul>
</div>
)}
</div>
);
}

Kompatibilitas - fitur yang jelas berikutnya. Tambahkan ke 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.compute(parsed.data);
res.json({
score: result.compatibility.score,
label: result.compatibility.label,
aspects: result.crossAspects,
});
});

Selesai. Satu endpoint, 50 kredit per panggilan, mengembalikan skor 0-100 dan cross-aspects.

Untuk engagement konten, horoskop harian - wajib ada. AstroWay menggeneratinya dari data transit real:

// The daily horoscope is keyed by sign and date, not by the birth chart.
const DailyInput = z.object({
sign: z.enum(['aries', 'taurus', 'gemini', 'cancer', 'leo', 'virgo',
'libra', 'scorpio', 'sagittarius', 'capricorn', 'aquarius', 'pisces']),
date: z.string(),
});
app.post('/api/horoscope/daily', async (req, res) => {
const parsed = DailyInput.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: parsed.error });
const horoscope = await client.horoscope.daily({ ...parsed.data, language: 'uk' });
res.json({
text: horoscope.horoscope,
disclaimer: horoscope.disclaimer, // must be shown in the UI!
});
});

Penting: Konten yang dihasilkan AI berisi disclaimer yang Anda wajibkan menunjukkan kepada pengguna (sesuai Terms of Service). Jangan hapus itu.

Horoskop harian sama untuk semua pengguna dengan tanggal lahir yang sama dan birth chart yang mirip. Cache secara agresif:

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.horoscope.daily(req.body);
cache.set(key, horoscope);
res.json(horoscope);
});

AstroWay juga memiliki caching server 5 menit bawaan (X-Cache: HIT), tetapi untuk konten yang bertahan lama diperlukan cache sendiri.

Platform apa pun akan cocok. Untuk memulai cepat - Vercel atau Railway:

Terminal window
# vercel.json
{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }

Di panel platform, set env ASTROWAY_API_KEY.

Jika sampai di sini - evaluasi konsumsi kredit bulanan sebelum peluncuran:

credits/month = DAU × (avg_charts_per_user × 20
+ avg_synastries × 50
+ avg_horoscopes × 20) × 30

Untuk 100 DAU dengan 1 chart + 1 horoskop + 0.3 sinastri per pengguna per hari:

100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits/month

Ini adalah plan Starter seharga $19/bulan (200K kredit).

Fitur canggih yang seharusnya ditambahkan pertumbuhan:

  • Overlay transit: /v1/transits menunjukkan posisi planet saat ini di birth chart
  • Progresi: /v1/progressions untuk busur perkembangan psikologis
  • Solar return: /v1/solar-return untuk “prediksi untuk tahun dari tanggal lahir”
  • Human Design: Human Design API membuka domain fungsionalitas yang sepenuhnya baru
  • Astrocartography: /v1/acg memetakan di mana pengguna seharusnya tinggal

Setiap fitur sulit untuk diimplementasikan dari awal, tetapi - satu panggilan API dengan AstroWay.

MakSeong · AstroWay

Aku membuat AstroWay API: membungkus Swiss Ephemeris ke dalam REST murni dan menulis tentang detail membosankan yang sebenarnya penting.

// bangun di atas ini

Swiss Ephemeris yang sama dengan Solar Fire - dalam 4 baris kode.

Kunci gratis tanpa kartu. 5.000 panggilan per bulan sebelum pembayaran pertama.

Lebih dari blog semua tulisan →

Ephemeris 2026-07-19

Bagaimana Kami Mengawasi Akurasi: CI vs swetest dan NASA

Akurasi dalam API Astro dapat menurun dengan mudah dari satu refaktor ephemeris. Kami memecahkan perlindungan: satu inti Swiss Ephemeris untuk aplikasi dan API, ratusan snapshot beku pada peta standar dan triangulasi setiap PR terhadap swetest CGI, Kerykeion, Prokerala, dan katalog kegelapan NASA.

Engineering 2026-07-15

Tiga resmi SDK: TypeScript, Python, PHP alih-alih curl mentah

HTTP mentah bekerja, tetapi klien yang terjenis menghemat jam: otomatis melengkapi jalur, jenis permintaan dan respons, retry bawaan untuk 408/409/429/5xx dan hierarki kesalahan Stainless-style. Kami jelaskan tiga resmi SDK - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) - dan bagaimana mereka dihasilkan dari satu kontrak OpenAPI.

Industry 2026-06-05

Free Astrology API: Which One Has the Best Free Tier in 2026?

A side-by-side of free tiers across the major astrology APIs - credits, request caps, card requirements - and how much you can actually build for free.