Doğum Haritası API'si

Temel URL: https://api.natalchart.ai. Her istek bir API anahtarı taşır, her yanıt JSON'dur ve her boylam, burca dönüştürülmeden önce derecenin dört ondalık basamağına kadar verilir. Anahtar ücretsizdir: bir NatalChart.AI hesabıyla giriş yapın ve bir anahtar oluşturun.

Hızlı başlangıç

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

Sitenin genelinde kullanılan örnek doğum verisi (1991-09-06, saat 18:30, Kiev) için yanıt. Gök cisimlerinden beşi gösteriliyor:

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

Yapay zekâ asistanları için MCP sunucusu

Aynı hesaplamalar, Claude, ChatGPT, Cursor ve VS Code için https://www.natalchart.ai/mcp adresinde bir MCP sunucusu olarak sunulur. Sunucu aynı anahtarla çalışır ve aynı günlük havuzdan harcar: her araç çağrısı bir istektir. Her istemci için kurulum: Yapay zekâ asistanları için MCP sunucusu.

Kimlik doğrulama

Anahtarı Authorization: Bearer nc_live_... olarak gönderin (X-API-Key başlığı da çalışır). Anahtarın tamamı yalnızca bir kez, oluşturduğunuzda gösterilir; biz yalnızca hash değerini saklarız. Bir hesapta en fazla beş etkin anahtar bulunabilir ve bunlardan herhangi biri anında iptal edilebilir. Anahtarları bir sunucuda tutun: tarayıcı ya da uygulama koduyla dağıtılan bir anahtarı herkes okuyabilir.

Doğum verileri

Harita hesaplayan uç noktalar tek bir nesne alır:

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

Uç noktalar

Tam harita

POST /v1/chart/full hesaplamanın tamamını yayımlanan örnek dosyayla aynı yapıda döndürür; böylece herhangi bir kod yazmadan önce bir yanıtı sabit bir haritayla karşılaştırabilirsiniz. Burada iki gök cismine, iki ev başlangıcına ve en sıkı iki açıya kısaltılmıştır:

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

Bölüm uç noktaları (planets, angles, houses, aspects, elements, fixed-stars), yalnızca o bölüme ihtiyaç duyan istemciler için aynı nesnenin birer bölümünü döndürür.

Günlük burç yorumu

POST /v1/horoscope/daily, günlük burç yorumunun hesaplanan yarısıdır: UTC'ye göre öğle vaktindeki gökyüzü, Ay'ın evresi ve burcu, önümüzdeki haftanın gökyüzü olayları ve birth gönderdiğinizde o haritaya yapılan her transit; her biri açısıyla, orbuyla, yaklaşan mı ayrılan mı olduğuyla, tam olduğu anla ve transit gök cisminin bulunduğu natal evle birlikte. Transit orbu Ay, Güneş, Merkür, Venüs ve Mars için 2°, daha yavaş gök cisimleri için 3° olarak alınır. İki alan astronomi değil, sabit kurallardır ve yanıt bunu belirtir: tone (üçgen ve altmışlık için supportive, kare ve karşıtlık için challenging, kavuşum için intensifying) ve focus, yani gezegen hızına ve sıkılığa göre en üst sırada yer alan üç temas. Yazılı metin yoktur; o kısım size kalır.

Örnek harita için 2026-09-18 tarihine ait gerçek bir yanıt; listeler iki öğeye kısaltılmıştır:

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

API Pro uç noktaları

Altı uç nokta; hepsi birlikte uygulamanın hesapladığı her şeyi kapsar. Aşağıdaki yanıtların her biri, örnek harita için verilmiş gerçek bir yanıtın kısaltılmış hâlidir; bir istekteki "...", yukarıda gösterilen doğum nesnesinin yerine geçer.

Bir dönemin transitleri

POST /v1/transits uç noktası birth, from ve to alanlarını (en fazla 92 gün) alır ve aralıktaki natal haritaya yapılan her tam transit açısını, her burca girişi ve her durağanlığı tarihe göre döndürür; ayrıca ilk gün etkin olan temasları evreleri ve tam oldukları anla birlikte verir.

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

Sinastri

POST /v1/synastry uç noktası personA ve personB alanlarını alır ve orblarıyla haritalar arası açıları, her kişinin gezegenlerinin diğerinin hangi evlerine düştüğünü ve altı yaşam alanının her biri için bir puanı döndürür. Buradaki ikinci kişi de kurgusaldır (1989-03-14, saat 07:45, New York).

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

Güneş dönüşü

POST /v1/solar-return uç noktası birth, year ve isteğe bağlı location alanlarını alır; Güneş'in natal boylamına döndüğü tam anı ve bu an için kurulan tam haritayı döndürür. Doğum saati gerektirir: saat olmadan natal Güneş'te yarım derecelik bir belirsizlik olur ve bu da dönüş anını yaklaşık on iki saat kaydırır.

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

Bir etkinlik için en iyi günler

POST /v1/timing uç noktası birth, bir activity (general, business, romance, health, creative, travel, home ya da clarity), from ve to (en fazla 62 gün) ve günlerin başlangıcını belirleyen isteğe bağlı bir timezone alır. Her gün, etkinlik için önemli olan gezegenlere göre ağırlıklandırılmış tam transit geometrisinden 0 ile 100 arasında puanlanır ve en iyi beş gün önce gelir. Gökyüzünü betimler; hiçbir gün için vaatte bulunmaz.

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

Bir haritaya göre tek bir yer

POST /v1/locations/score uç noktası birth ve koordinatları içeren bir location alır. Harita o yere taşınır; yanıt, taşınmış haritanın köşe noktalarını, bunların üzerindeki gezegenleri orblarıyla, her yaşam alanı için 0 ile 10 arasında bir puanı (5 nötrdür) ve haritanın o yere genel olarak ne kadar güçlü tepki verdiğini gösterir: bir ana gezegen bir köşe noktasına 2° içinde yakınsa güçlü, 4° içindeyse orta, aksi hâlde zayıf.

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

Bir harita için en iyi şehirler

POST /v1/locations/rank uç noktası birth, isteğe bağlı bir focus (identity, love, body, money, home, mind değerlerinden dilediğiniz), isteğe bağlı bir region ve 3 ile 12 arasında bir limit alır ve 61 büyük şehirden oluşan bir kataloğu sıralar. Dünyadaki her şehir karşılaştırılmaz; başka herhangi bir yer, yukarıdaki uç noktayla puanlanabilir.

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

Limitler ve fiyatlar

İstekler hesap başına, hesabın tüm anahtarları birlikte sayılır ve havuz 00:00 UTC'de yenilenir. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır. Geçersiz olduğu için reddedilen bir istek sayılmaz, bizim tarafımızda başarısız olan bir hesaplama havuza geri eklenir ve GET /v1/usage her zaman ücretsizdir. API Pro, uygulama planlarından ayrı bir aboneliktir: uygulamanın Premium planını kapsamaz, uygulamanın Premium planı da API Pro'yu kapsamaz. İki havuz da birbirinden ayrıdır: uygulama yapay zekâ yanıtlarını haftalık, bu API ise hesaplamaları UTC gününe göre sayar ve biri diğerinden harcamaz.

Hatalar

Her hata aynı yapıdadır: { "error": { "code", "message", "details"?, "docs" } }.

Hesaplama ayarları

Bu ayarlar sabittir ve uygulamanın kendi ayarlarıdır; tamamı Haritanızı doğrulayın sayfasında açıklanır ve doğruluk raporunda NASA'nın JPL Horizons verileriyle karşılaştırılarak kontrol edilir. Swiss Ephemeris veri dosyaları, hız bayrağı açık. Tropikal zodyak, yer merkezli, görünür konumlar. Placidus ev sistemi. Gerçek Ay düğümü. Lilith, oskülatör Ay apojesi olarak. Şans Noktası, gündüz ve gece haritalarında aynı biçimde ASC + Ay − Güneş olarak. Yalnızca beş majör açı: kavuşum 8°, altmışlık 6°, kare 8°, üçgen 8°, karşıt 8°. Her natal ve transit açı, iki gök cisminin hızlarına göre (retro hareket de dahil) yaklaşan mı ayrılan mı olduğunu belirtir.

Gizlilik

Doğum verileri kişisel veridir. API bunları okur, hesaplar, yanıtlar ve unutur: hiçbir istek gövdesi saklanmaz ve gönderdiğiniz hiçbir şey yanıt dışında bir amaçla kullanılmaz. Her istek için sakladıklarımız uç nokta, durum kodu ve yanıt süresidir. Gizlilik politikasına bakın.

Sorular