Astroloji Uygulaması Oluşturma Kılavuzu: Geliştiriciler için Tam Rehber

🕓 2026-04-14 tarihinde yapılan kaydın 2026-05-09’da güncellenmiş hali. TS / Python / PHP SDK artık public registries’de yaşıyor — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Ayrıntılar için changelog.

Bir astroloji uygulaması yapmak istiyorsun. Nereden başlayacaksın? Bu rehberde, kararlar ve kodlar: API seçiminden çalışır bir ürünün dağıtımı.

Mimari Soruları

Kodu yazmadan önce, düşünmen gerekenler: hesaplamalar istemci tarafında mı yoksa sunucu tarafında mı yapılmalı?

İstemci (örneğin, Swiss Ephemeris WASM tarayıcıda):

Artılar: sorgu maliyeti yok, çevrimdışı çalışır, tam kontrol
Eksiler: ~2 MB WASM her kullanıcı için, lisanslama zor (ticari kullanım için Swiss Ephemeris kısıtlamaları var), sen hesaplamalı kodu yönetiyorsun

Sunucu API (AstroWay, Prokerala vb.):

Artılar: istemci bağımlılıkları yok, küçük uygulama paketi, mobil cihazlarda hızlı, lisans sorunları yok
Eksiler: sorgu maliyeti, “soğuk” sorgularda gecikme

Çoğu uygulama için sunucu API daha iyi bir seçim. Mobil kullanıcılar 2 MB WASM beklemeyecek; lisanslı ürünlerle uğraşmak istemeyeceksin; modern API’ler aynı sorguları ücretsiz olarak önbelleğe alır (AstroWay, X-Cache: HIT başlığıyla 5 dakikalık önbellek yapar).

API Seçimi

Ne önemlidir:

Doğruluk — Swiss Ephemeris “motorunda” arama yap (±1 açısal saniye). API bunu doğrudan söylemiyorsa — sor.
Kapsam — doğum + sinastri + transitler — minimum. İlerlemeler ve geri dönüşler — sonraki seviye. Nadir teknikler (düzeltme, İnsan Tasarımı) — ayırt edici.
SDK Kalitesi — tiplenmiş TypeScript ve Python SDK’leri saatlerce zaman kazandırır.
Fiyatlandırma Modeli — kredi tabanlı model, karma yüklerde per-sorgu modelinden daha iyi ölçeklenir.

Bu öğretici için AstroWay API’sini kullanacağız, çünkü dört önemli özelliğe de sahip: 723 endpoint, Swiss Ephemeris, tiplenmiş SDK’lar, kredi tabanlı fiyatlandırma.

Adım 1: Backend Ayarlama

Asla bir astroloji API’sini doğrudan tarayıcıdan çağıurma — API anahtarın sızabilir. Her zaman kendi backend’in üzerinden geç.

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

src/server.ts oluştur:

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

Çalıştır:

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

Deneme için curl kullan:

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

Tam bir JSON doğum haritası alırsın.

Adım 2: Frontend

Herhangi bir framework uygun. Örnekte React ile basit bir form kullanacağız:

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 (örneğin 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>Harita Oluştur</button>
      </form>

      {chart && (
        <div>
          <h2>Gezegenler</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (ev {p.house})</li>
            ))}
          </ul>
          <h2>Aspektler</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>
  );
}

Adım 3: Sinastri

Uygunluk — sonraki doğal özellik. src/server.ts dosyasına ekle:

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

Tümünü yaptı. Bir endpoint, 50 kredi/sorgu, 0-100 arası puan ve çapraz aspektler döndürür.

Adım 4: Günlük Burçlar

İçerik katılımı için günlük burçlar —必须. AstroWay, gerçek transit verilerini kullanarak bunları üretir:

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'da göstermek zorundasın!
  });
});

Önemli: AI tarafından oluşturulan içerik, kullanıcıya göstermek zorunda olduğun bir açıklama içerir (Hizmet Koşulları gereği). Onu kaldırma.

Adım 5: Önbelleğe Alma

Günlük burçlar, aynı doğum gününe ve benzer doğum haritalarına sahip tüm kullanıcılar için aynıdır. Agresif bir şekilde önbelleğe al:

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’de ayrıca 5 dakikalık sunucu tarafı önbelleğe alma (X-Cache: HIT) vardır, ancak uzun süreli içerik için kendi önbelleğin gerekir.

Adım 6: Dağıtım

Herhangi bir platform uygun. Hızlı başlangıç için — Vercel veya Railway:

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

Platform panosunda ASTROWAY_API_KEY ortam değişkenini ayarla.

Bütçe Planlama

Eğer buraya kadar geldin — lansman öncesi aylık kredi tüketimini değerlendir:

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

100 DAU ile 1 harita + 1 burç + 0.3 sinastri kullanıcı başına gün:

100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 kredi / ay

Bu, Starter planı için $19/ay (200K kredi) anlamına gelir.

Sonraki Adımlar

Uygulamanın büyümesiyle eklenmesi gereken gelişmiş özellikler:

Transit üst örtüsü — /v1/transits doğum haritasındaki güncel gezegen konumlarını gösterir
İlerlemeler — /v1/progressions psikolojik gelişim için
Güneş dönüşü — /v1/solar-return “doğum gününden bir yıl sonraki tahmin” için
İnsan Tasarımı — İnsan Tasarımı API tamamen yeni bir işlevsel alan açar
Astrolojik haritalama — /v1/acg kullanıcıya nerede yaşaması gerektiğini gösterir

Her özellik, sıfırdan uygulanması zor ama — AstroWay ile bir API çağrısı.

Başlangıç

Ücretsiz API anahtarını al — 10 000 kredi / ay
Tam API referansı — tüm 723 endpoint
Doğum Haritası API — endpoint için ayrıntılı dökümantasyon

AstroWay team

AstroWay API mühendislik ekibi. Swiss Ephemeris'i temiz bir REST'e sarıp aslında önemli olan sıkıcı detaylar hakkında yazıyoruz.

// bunu kullanarak inşa et

Solar Fire'daki aynı Swiss Ephemeris — 4 satır kodla.

Kart gerekmeden ücretsiz anahtar. İlk ödemeye kadar ayda 5.000 istek.

API anahtarı al → Dokümantasyon