🪐 Swiss Ephemeris 2.10 & NASA JPL DE431 Core

NatalKit Geliştirici API Dokümantasyonu

NatalKit REST API; astronomik hassasiyet seviyesinde doğum haritası (natal chart), sinastri (uyum analizi), transit takvimleri, secondary progressions ve 10 farklı dünya astroloji geleneğini tek bir entegre arayüzde sunan kurumsal düzeyde bir astroloji motorudur.

🛰️ Yay-Saniyesi Astronomik Hassasiyet

CGO Swiss Ephemeris çekirdeği ile gezegen koordinatları, retro hareketler ve ev cusp'ları 0.0001° hassasiyetle hesaplanır.

🏛️ 10 Kadim Astroloji Sistemi

Klasik Batı, Hint Vedik (Jyotish/Lahiri), Helenistik, Çin BaZi (Dört Sütun), Maya Tzolk'in ve diğer kadim sistemler tek endpoint'te.

⚡ Sub-Millisecond & Global CDN

Önbellek katmanı, otomatik zaman dilimi (IANA) çözümleme ve geocoding desteği ile dakikada binlerce istek işleme kapasitesi.

🔑 Kimlik Doğrulama (Authentication)

NatalKit API, tüm isteklerde X-API-Key başlığı üzerinden kimlik doğrulaması yapar. API anahtarınızı güvenli tutun ve istemci taraflı (frontend) kodlarda doğrudan ifşa etmeyin.

Header X-API-Key: nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 Güvenlik Notu:

API anahtarınızı URL query parametreleri içinde göndermeyin. Tüm endpoint'ler HTTPS protokolü üzerinden X-API-Key header'ı ile çağrılmalıdır.

🪙 Kredi Modeli & Kota Yönetimi

Her API isteği, hesaplama maliyetine göre önceden tanımlı kredi havuzunuzdan düşülür:

Endpoint	İşlem	Kredi Maliyeti
`/v1/natal`	Doğum Haritası (Gezegenler, Evler, Açılar)	1 Kredi
`/v1/synastry`	Çift Uyumu & 5 Sütun Sinastri Skoru	5 Kredi
`/v1/transits`	Gezegen Transitleri & Tetikleyici Olaylar	3 Kredi
`/v1/progressions`	Secondary Progressions (İlerletimler)	3 Kredi
`/v1/systems`	Sistem Listesi ve Metadata	0 Kredi (Ücretsiz)
`/v1/systems/{sys}`	Belirli Bir Kültürel Astroloji Geleneği	2 Kredi
`/v1/horoscope/weekly`	Haftalık Burç Yorumu	2 Kredi
`/v1/horoscope/monthly`	Aylık Burç Yorumu	2 Kredi
`/v1/horoscope/personal`	Kişisel Transit Analizi & Günlük Yorum	3 Kredi

Doğum Haritası Hesaplama

POST https://natalkit.com/v1/natal 1 Credit

Verilen doğum tarihi, saati ve koordinatları için İsviçre Efemerisi (Swiss Ephemeris) motorunu çalıştırarak gezegen pozisyonları, ev kuspisleri, çapraz açılar, element/nitelik dengesi ve harita şeklini döndürür.

İstek Parametreleri (JSON Body)

Parametre	Tip	Açıklama
name opsiyonel	string	Kişi veya profil adı (Örn: "Ahmet Yılmaz").
date zorunlu	string	Doğum tarihi (ISO Format: `YYYY-MM-DD`).
time opsiyonel	string	Doğum saati (`HH:MM`). Bilinmiyorsa boş bırakılabilir veya `time_unknown: true` verilebilir.
lat zorunlu	float	Enlem koordinatı (-90.0 ile 90.0 arası).
lon zorunlu	float	Boylam koordinatı (-180.0 ile 180.0 arası).
city opsiyonel	string	Doğum şehri (Örn: "Istanbul").
country opsiyonel	string	2 haneli ISO ülke kodu (Örn: "TR").
timezone opsiyonel	string	IANA Zaman Dilimi (Örn: `Europe/Istanbul`). Belirtilmezse koordinatlardan otomatik çözümlenir.
house_system opsiyonel	string	Ev sistemi: `P` (Placidus - Varsayılan), `W` (Whole Sign), `K` (Koch), `E` (Equal).

curl -X POST "https://natalkit.com/v1/natal" \
  -H "X-API-Key: nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "date": "1994-07-16",
    "time": "14:45",
    "city": "Istanbul",
    "lat": 41.0082,
    "lon": 28.9784,
    "timezone": "Europe/Istanbul",
    "house_system": "P"
  }'

Response Example 200 OK

{
  "engine_version": "2.10.03",
  "birth": {
    "name": "Alex",
    "date": "1994-07-16",
    "time": "14:45",
    "city": "Istanbul"
  },
  "ascendant": 218.42,
  "midheaven": 128.15,
  "planets": [
    { "body": "Sun", "sign": "Cancer", "degree": 23.78, "house": 9, "speed": 0.95 },
    { "body": "Moon", "sign": "Scorpio", "degree": 14.12, "house": 1, "speed": 12.45 },
    { "body": "Venus", "sign": "Virgo", "degree": 4.88, "house": 10, "speed": 1.12 }
  ],
  "houses": [ ... ],
  "aspects": [
    { "body1": "Sun", "body2": "Moon", "aspect": "trine", "orb": 1.34 }
  ]
}

İlişki & Çift Uyumu (Sinastri)

POST https://natalkit.com/v1/synastry 5 Credits

İki kişinin doğum verilerini eşzamanlı hesaplayarak aralarındaki çapraz gezegen açılarını, 5 temel ilişki sütunu skorunu (Romantik Çekim, Duygusal Güven, Zihinsel Uyum, Uzun Vadeli Kalıcılık, Karmik Bağ) ve ortak orta nokta (Composite Midpoint) haritasını üretir.

İstek Parametreleri (JSON Body)

Parametre	Tip	Açıklama
person_a zorunlu	object	1. Kişinin doğum parametreleri (`date`, `time`, `lat`, `lon`, `name`).
person_b zorunlu	object	2. Kişinin (Partner) doğum parametreleri (`date`, `time`, `lat`, `lon`, `name`).

curl -X POST "https://natalkit.com/v1/synastry" \
  -H "X-API-Key: nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_a": {
      "name": "Can",
      "date": "1992-05-14",
      "time": "09:30",
      "lat": 41.0082, "lon": 28.9784,
      "timezone": "Europe/Istanbul"
    },
    "person_b": {
      "name": "Selin",
      "date": "1994-11-20",
      "time": "18:15",
      "lat": 39.9334, "lon": 32.8597,
      "timezone": "Europe/Istanbul"
    }
  }'

Response Example 200 OK

{
  "person_a": "Can",
  "person_b": "Selin",
  "overall_score": 88,
  "verdict": "Yüksek tutku ve güçlü duygusal güven içeren uyumlu bir bağ.",
  "romantic": { "score": 92, "title": "Romantik & Fiziksel Çekim" },
  "emotional": { "score": 85, "title": "Duygusal Güven & Ruh Bağı" },
  "mental": { "score": 88, "title": "Zihinsel Akıcılık" },
  "composite_chart": [
    { "body": "Sun", "sign": "Libra", "degree": 12.45 },
    { "body": "Venus", "sign": "Scorpio", "degree": 8.12 }
  ]
}

Gezegen Transitleri & Takvim

POST https://natalkit.com/v1/transits 3 Credits

Kişinin natal haritası üzerine seçilen zaman aralığında (6 ay — 5 yıl) gerçekleşen tüm majör gökyüzü transitlerini, exact temas tarihlerini ve etki sürelerini hesaplar.

İstek Parametreleri (JSON Body)

Parametre	Tip	Açıklama
birth zorunlu	object	Doğum haritası parametreleri (`date`, `time`, `lat`, `lon`).
range opsiyonel	string	Transit zaman aralığı: `6m`, `1y`, `2y`, `3y` (Varsayılan), `5y`.

curl -X POST "https://natalkit.com/v1/transits" \
  -H "X-API-Key: nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "date": "1990-03-21",
      "time": "06:30",
      "lat": 41.0082, "lon": 28.9784,
      "timezone": "Europe/Istanbul"
    },
    "range": "1y"
  }'

10 Kadim Astroloji Sistemi

GET https://natalkit.com/v1/systems 0 Credit (Ücretsiz)

POST https://natalkit.com/v1/systems/{system_id} 2 Credits

NatalKit'in desteklediği 10 kadim astrolojik geleneği (Vedic, Hellenistic, Chinese BaZi, Mayan, Tibetan, Celtic, Persian, Japanese, Thai) sorgular ve belirtilen sistemin özel haritasını hesaplar.

Desteklenen Sistem Tanımlayıcıları ({system_id})

system_id	Gelenek	Açıklama
`western`	Batı Tropikal	Placidus / Koch evleri ve modern gezegenler.
`vedic`	Hint Vedik (Jyotish)	Lahiri Ayanamsa, Nakshatra'lar ve D9 Navamsha haritası.
`hellenistic`	Klasik Helenistik	Whole Sign evleri, Sect (Gece/Gündüz) ve Hermetik Noktalar.
`bazi`	Çin Dört Sütunu (BaZi)	Yıl, Ay, Gün ve Saat sütunları, 10 Gods matrisi, Gizli Kökler.
`mayan`	Maya Tzolk'in	260 günlük kutsal takvim, Kin sayısı ve Trecena Burcu.
`tibetan`	Tibet Astrolojisi (Kar-Tsi)	Mewa 9 element kareleri ve Parkha 8 Trigram döngüsü.
`celtic`	Kelt Ağaç Astrolojisi	13 Ogham ay ağacı ve Druid totemik koruyucuları.
`persian`	Pers / Ortaçağ Arap	Arap Noktaları (Lot of Fortune, Spirit) ve Hyleg hesaplaması.
`japanese`	Japon Onmyōdō (陰陽道)	Gogyō 5 Element dengesi ve Eto Zodyak döngüsü.
`thai`	Tayland Horasart (โหราศาสตร์)	Maha Songkran 12 Hayvan yılı ve Doğum günü koruyucu gezegeni.

curl -X POST "https://natalkit.com/v1/systems/bazi" \
  -H "X-API-Key: nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1988-08-08",
    "time": "08:08",
    "lat": 41.0082, "lon": 28.9784,
    "timezone": "Europe/Istanbul"
  }'

Response Example 200 OK

{
  "system": "bazi",
  "name": "Çin Dört Sütun Astrolojisi (BaZi)",
  "year_pillar": { "stem": "Yang Earth (Wu)", "branch": "Dragon (Chen)", "animal": "Toprak Ejderhası" },
  "month_pillar": { "stem": "Yang Metal (Geng)", "branch": "Monkey (Shen)" },
  "day_pillar": { "stem": "Yin Water (Gui)", "branch": "Ox (Chou)" },
  "hour_pillar": { "stem": "Yang Fire (Bing)", "branch": "Dragon (Chen)" },
  "day_master": "Yin Water (Gui)",
  "favorable_elements": ["Metal", "Water"]
}

⚠️ Hata Kodları (Error Codes)

API hataları, standart HTTP durum kodları ve JSON formatında makine tarafından okunabilir hata nesneleriyle döner:

HTTP Status	Hata Kodu (Code)	Açıklama
400	INVALID_REQUEST	Gönderilen JSON gövdesi veya parametreler geçersiz/eksik.
401	INVALID_API_KEY	API anahtarı eksik, geçersiz, iptal edilmiş veya hatalı formatta.
402	INSUFFICIENT_CREDITS	Abonelik kredi kotanız yetersiz. Lütfen kredi yükleyin.
403	IP_NOT_ALLOWED	İsteğin geldiği IP adresi anahtarın IP beyaz listesinde yer almıyor.
403	ENDPOINT_NOT_ALLOWED	API anahtarınızın bu endpoint için yetkisi bulunmuyor.
403	CUSTOMER_SUSPENDED	Müşteri hesabı geçici olarak durdurulmuş.
404	UNKNOWN_SYSTEM	İstenen astrolojik sistem tanımlayıcısı bulunamadı.
429	RATE_LIMIT_EXCEEDED	Dakikalık (RPM) veya günlük (RPD) istek kotası aşıldı.
500	INTERNAL_ERROR	Swiss Ephemeris motoru veya sunucu hesaplama hatası.