AstroWay/api v2.295.7 · tr
tüm sistemler normal

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

Astroloji uygulamasını sıfırdan oluşturma adımları - API seçimi, mimari, ilk doğum haritası, sinastri ve transitler eklenmesi, dağıtım.

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

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

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

Astroloji API’sini asla doğrudan tarayıcıdan çağırma - API anahtarın sızar. Her zaman kendi backend’in üzerinden git.

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

src/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:

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

curl ile kontrol:

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

Tam bir JSON natal haritası alırsın.

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

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.

İç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.

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.

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

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

Platform panelinde ASTROWAY_API_KEY ortam değişkenini ayarla.

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

Gü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/month

Bu, aylık 19 dolarlık (200K kredi) Başlangıç planı.

Büyüdükçe eklemeye değer gelişmiş özellikler:

  • Transit Yerleşimi: /v1/transits gezegenlerin 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/acg kullanı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.

MakSeong · AstroWay

I build the AstroWay API: Swiss Ephemeris on a clean REST surface, and I write about the dull parts that turn out to matter.

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

Daha fazla blog yazısı tüm yazılar →

Ephemeris 2026-07-19

Doğruluğu nasıl kontrol altında tutuyoruz: swetest ve NASA'ya karşı CI

Bir astroloji API'sinde doğruluk, efemeris kodundaki tek bir refactoring ile kolayca bozulabilir. Korumayı inceliyoruz: uygulama ve API için tek bir Swiss Ephemeris çekirdeği, referans haritalar üzerinde yüzlerce dondurulmuş snapshot ve her PR'ın swetest CGI, Kerykeion, Prokerala ve NASA tutulma kataloğuna karşı üçgenlenmesi.

Engineering 2026-07-15

Üç resmi SDK: ham curl yerine TypeScript, Python, PHP

Ham HTTP çalışır, ama tipli bir istemci saatler kazandırır: yol otomatik tamamlama, istek ve yanıt tipleri, 408/409/429/5xx için yerleşik retry ve Stainless tarzı hata hiyerarşisi. Üç resmi SDK'yı, @astroway/sdk (npm), astroway (PyPI) ve astroway/sdk (Packagist), ve bunların tek bir OpenAPI sözleşmesinden nasıl üretildiğini inceliyoruz.

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.