🕓 Kayıt tarihi 2026-04-14, güncellendi 2026-05-09. TS / Python / PHP SDK’ları artık herkese açık kayıtlarda bulunuyor -
@astroway/sdk(npm),astroway(PyPI),astroway/sdk(Packagist). Detaylar için changelog.
Astroloji uygulaması mı yapmak istiyorsun? Nereden başlamalı? Bu rehberde, API seçiminden çalışan bir ürünün dağıtımına kadar çözümler ve kodlar bulacaksın.
Mimari Sorunlar
Section titled “Mimari Sorunlar”Kod yazmadan önce belirle: hesaplamalar istemcide mi yoksa sunucuda mı yapılacak?
İstemci (örneğin, tarayıcıda Swiss Ephemeris WASM):
- Artıları: istek başına maliyet yok, çevrimdışı çalışır, tam kontrol
- Eksileri: her kullanıcı için ~2 MB WASM, karmaşık lisanslama (Swiss Ephemeris’in ticari kullanımı kısıtlamalara sahiptir), hesaplama kodunu kendin sürdürürsün
Sunucu API’si (AstroWay, Prokerala vb.):
- Artıları: istemci bağımlılıkları yok, küçük uygulama paketi, mobilde hızlı, lisans derdi yok
- Eksileri: istek başına kredi maliyeti, “soğuk” isteklerde gecikme
Çoğu uygulama için sunucu API’si kazanır. Mobil kullanıcılar 2 MB WASM beklemeyecektir; lisanslama nüanslarıyla uğraşmaya değmez; ve modern API’ler aynı istekleri ücretsiz olarak önbelleğe alır (AstroWay, X-Cache: HIT başlığıyla 5 dakikalık bir önbellek oluşturur).
API Seçimi
Section titled “API Seçimi”Neler önemli:
- Doğruluk: “kaputun altında” Swiss Ephemeris’i ara (±1 açısal saniye). Eğer API bunu açıkça belirtmiyorsa - sor.
- Kapsam: natal + sinastri + transitler: minimum. Progresyonlar ve dönüşler - bir sonraki seviye. Nadir teknikler (rektifikasyon, Human Design) - bir farklılaştırıcıdır.
- SDK Kalitesi: tip tanımlı TypeScript ve Python SDK’ları saatler kazandırır.
- Fiyatlandırma Modeli: kredi tabanlı, karma yüklerde istek başına olandan daha iyi ölçeklenir.
Bu eğitim için AstroWay API’yi kullanacağız, çünkü dördüne de sahip (777 endpoint, Swiss Ephemeris, tip tanımlı SDK’lar, kredi tabanlı).
Adım 1: Backend’i Kurmak
Section titled “Adım 1: Backend’i Kurmak”Astroloji API’sini asla doğrudan tarayıcıdan çağırma - API anahtarın sızar. Her zaman kendi backend’in üzerinden git.
mkdir my-astrology-appcd my-astrology-appnpm init -ynpm install express @astroway/sdk zodnpm install -D typescript @types/express @types/node tsxsrc/server.ts dosyasını 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.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'));Çalıştır:
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.tscurl ile kontrol:
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 natal haritası alırsın.
Adım 2: Frontend
Section titled “Adım 2: Frontend”Herhangi bir framework uygun olacaktır. Örnek olarak - basit bir form ile React:
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> );}Adım 3: Sinastri
Section titled “Adım 3: Sinastri”Uyumluluk - bir sonraki bariz ö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.compute(parsed.data); res.json({ score: result.compatibility.score, label: result.compatibility.label, aspects: result.crossAspects, });});Hepsi bu. Tek bir endpoint, çağrı başına 50 kredi, 0–100 arası bir puan ve çapraz açılar döndürür.
Adım 4: Günlük Burç Yorumları
Section titled “Adım 4: Günlük Burç Yorumları”İçerik etkileşimi için günlük burç yorumları olmazsa olmazdır. AstroWay bunları gerçek transit verilerinden üretir:
// 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! });});Önemli: AI tarafından oluşturulan içerik, kullanıcılara göstermek zorunda olduğun bir sorumluluk reddi beyanı (Hizmet Şartları’na göre) içerir. Bunu kaldırma.
Adım 5: Önbellekleme
Section titled “Adım 5: Önbellekleme”Günlük burç yorumları, aynı doğum gününe ve benzer natal haritalara 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.horoscope.daily(req.body); cache.set(key, horoscope); res.json(horoscope);});AstroWay’de ayrıca yerleşik 5 dakikalık sunucu tarafı önbellekleme (X-Cache: HIT) bulunur, ancak uzun ömürlü içerik için kendi önbelleğin gereklidir.
Adım 6: Dağıtım
Section titled “Adım 6: Dağıtım”Herhangi bir platform uygun olacaktır. Hızlı başlangıç için - Vercel veya Railway:
# vercel.json{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }Platform panelinde ASTROWAY_API_KEY ortam değişkenini ayarla.
Bütçe Planlaması
Section titled “Bütçe Planlaması”Buraya kadar geldiysen - lansmandan önce aylık kredi tüketimini tahmin et:
credits/month = DAU × (avg_charts_per_user × 20 + avg_synastries × 50 + avg_horoscopes × 20) × 30Günde kullanıcı başına 1 harita + 1 burç yorumu + 0.3 sinastri ile 100 DAU için:
100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits/monthBu, aylık 19 dolarlık (200K kredi) Başlangıç planı.
Sırada Ne Var
Section titled “Sırada Ne Var”Büyüdükçe eklemeye değer gelişmiş özellikler:
- Transit Yerleşimi:
/v1/transitsgezegenlerin natal haritadaki mevcut konumlarını gösterir - Progresyonlar: psikolojik gelişim yayları için
/v1/progressions - Solar Dönüş: “doğum gününden itibaren bir yıllık tahmin” için
/v1/solar-return - Human Design: Human Design API yepyeni bir fonksiyonel alanı açar
- Astrokartografi:
/v1/acgkullanıcının nerede yaşaması gerektiğini haritalar
Her özellik sıfırdan uygulaması zordur, ancak AstroWay ile tek bir API çağrısı yeterlidir.
Başlangıç
Section titled “Başlangıç”- Ücretsiz API anahtarını al: Ayda 10.000 kredi
- Tam API referansı: tüm 777 endpoint
- Birth Chart API: harita endpoint’inin detaylı dokümantasyonu
Solar Fire'daki aynı Swiss Ephemeris - 4 satır kodla.
Kart gerekmeden ücretsiz anahtar. İlk ödemeye kadar ayda 5.000 istek.