Membangun Aplikasi Astrologi: Panduan Lengkap untuk Pengembang

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

Kamu ingin membuat aplikasi astrologi. Dari mana harus memulai? Di panduan ini — solusi dan kode: dari memilih API hingga deploy produk yang berfungsi.

Pertanyaan Arsitektur

Sebelum menulis kode, pertimbangkan: komputasi di klien atau di server?

Klien (misalnya, Swiss Ephemeris WASM di browser):

Kelebihan: tanpa biaya per permintaan, berfungsi offline, kontrol penuh
Kekurangan: ~2 MB WASM per pengguna, lisensi yang rumit (penggunaan komersial Swiss Ephemeris memiliki batasan), kamu sendiri yang memelihara kode komputasi

Server API (AstroWay, Prokerala, dll.):

Kelebihan: tanpa ketergantungan klien, bundle aplikasi kecil, cepat di mobile, tanpa sakit kepala lisensi
Kekurangan: biaya dalam kredit per permintaan, keterlambatan pada permintaan “dingin”

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

Pemilihan API

Apa yang penting:

Akurasi — cari Swiss Ephemeris “di bawah kap” (±1 detik busur). Jika API tidak secara langsung mengatakan itu — tanyakan.
Cakupan — nativitas + sinastria + transito — minimum. Progresi dan return — level berikutnya. Teknik langka (rektifikasi, Human Design) — ini diferensiator.
Kualitas SDK — TypeScript dan Python SDK yang ditentukan jenisnya menghemat jam.
Model tarif — credit-based lebih baik daripada per permintaan, pada beban yang bervariasi.

Untuk tutorial ini, kita akan menggunakan AstroWay API, karena memiliki keempat hal tersebut (723 endpoint, Swiss Ephemeris, SDK yang ditentukan jenisnya, credit-based).

Langkah 1: Membuat Backend

Jangan pernah memanggil API astrologi langsung dari browser — kunci API-mu akan bocor. Selalu lewati backend-mu.

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({
      ...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:

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

Periksa melalui 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}'

Dapatkan kartu nativitas JSON lengkap.

Langkah 2: Frontend

Framework apa pun bisa digunakan. Untuk contoh — React dengan form sederhana:

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 (misalnya 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}: {p.sign} (house {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>
  );
}

Langkah 3: Sinastria

Kesesuaian — fitur berikutnya yang jelas. Tambahkan di 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,
  });
});

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

Langkah 4: Horoskop Harian

Untuk konten yang menarik, horoskop harian — harus ada. AstroWay menghasilkannya dari data transito yang nyata:

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, // wajib disimpan di UI!
  });
});

Penting: Konten yang dihasilkan AI mengandung disclaimer, yang wajib kamu tampilkan kepada pengguna (sesuai Terms of Service). Jangan hapus itu.

Langkah 5: Penyimpanan Cache

Horoskop harian sama untuk semua pengguna dengan hari lahir yang sama dan kartu nativitas yang mirip. Cache 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.horoscopeDaily(req.body);
  cache.set(key, horoscope);
  res.json(horoscope);
});

Di AstroWay juga ada cache server yang terintegrasi (5-menit, X-Cache: HIT), tapi untuk konten yang bertahan lama, cache sendiri diperlukan.

Langkah 6: Deploy

Platform apa pun bisa digunakan. Untuk memulai cepat — Vercel atau Railway:

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

Di panel platform, atur env ASTROWAY_API_KEY.

Perencanaan Anggaran

Jika kamu sampai di sini — perkirakan konsumsi kredit bulanan sebelum meluncurkan:

kredit/bulan = DAU × (rata-rata_chart_per_pengguna × 20
                     + rata-rata_sinastria × 50
                     + rata-rata_horoskop × 20) × 30

Untuk 100 DAU dengan 1 kartu + 1 horoskop + 0,3 sinastria per pengguna per hari:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 kredit / bulan

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

Apa Selanjutnya

Fitur yang ditingkatkan, yang sebaiknya ditambahkan dengan pertumbuhan:

Overlay transito — /v1/transits menampilkan posisi planet saat ini di kartu nativitas
Progresi — /v1/progressions untuk busur psikologis perkembangan
Solar return — /v1/solar-return untuk “prediksi tahunan sejak hari lahir”
Human Design — Human Design API membuka domain fungsional baru
Astrocartography — /v1/acg memetakan di mana pengguna sebaiknya tinggal

Setiap fitur sulit diimplementasikan dari awal, tapi — satu tantangan API dengan AstroWay.

Mulai

Dapatkan kunci API gratis — 10 000 kredit / bulan
Referensi API lengkap — semua 723 endpoint
Birth Chart API — dokumentasi endpoint kartu yang detail

AstroWay team

Tim rekayasa AstroWay API. Kami membungkus Swiss Ephemeris dalam REST bersih 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.

Dapatkan kunci API → Dokumentasi