API للخريطة الفلكية

عنوان URL الأساسي: https://api.natalchart.ai. يحمل كل طلب مفتاح API، وتأتي كل استجابة بصيغة JSON، ويُعطى كل طول بروجي بأربع منازل عشرية من الدرجة قبل تحويله إلى برج. والمفتاح مجاني: يكفي تسجيل الدخول بحساب NatalChart.AI ثم إنشاء مفتاح.

بداية سريعة

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

الاستجابة لبيانات الميلاد التوضيحية المستخدمة في أنحاء هذا الموقع (1991-09-06، 18:30، كييف). ويظهر فيها خمسة من الأجرام:

{
  "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"
  ]
}

خادم MCP لمساعدي الذكاء الاصطناعي

الحسابات نفسها متاحة في صورة خادم MCP على https://www.natalchart.ai/mcp، للاستخدام مع Claude وChatGPT وCursor وVS Code. ويعمل بالمفتاح نفسه ويستهلك الحصة اليومية نفسها، بطلب واحد لكل استدعاء أداة. وإعداد كل عميل في صفحة خادم MCP لمساعدي الذكاء الاصطناعي.

المصادقة

يُرسَل المفتاح بصيغة Authorization: Bearer nc_live_...‎ (وتصلح الترويسة X-API-Key أيضًا). يُعرض المفتاح كاملًا مرة واحدة عند إنشائه، ولا نحتفظ منه إلا بقيمة تجزئته. ويمكن أن يضم الحساب حتى خمسة مفاتيح نشطة، وأن يُبطل أيًّا منها فورًا. ويُرجى إبقاء المفاتيح على خادم: فالمفتاح المضمَّن في شيفرة المتصفح أو التطبيق يستطيع أي شخص قراءته.

بيانات الميلاد

تستقبل نقاط النهاية (endpoints) التي تحسب خريطة كائنًا واحدًا:

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

نقاط النهاية

الخريطة الكاملة

تُرجع نقطة النهاية POST /v1/chart/full الحساب كاملًا بالبنية نفسها التي في الملف التوضيحي المنشور، لذا يمكنك مقارنة الاستجابة بخريطة ثابتة قبل كتابة أي شيفرة. وهي مختصرة هنا إلى جرمين ورأسين من رؤوس البيوت وأدق جانبين:

{
  "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
  }
}

أما نقاط النهاية الجزئية (planets، angles، houses، aspects، elements، fixed-stars) فتُرجع كل منها جزءًا واحدًا من الكائن نفسه، لمن يحتاج إلى ذلك الجزء وحده.

الأبراج اليومية

نقطة النهاية POST /v1/horoscope/daily هي النصف المحسوب من الأبراج اليومية: السماء عند الظهر بتوقيت UTC، وطور القمر وبرجه، والأحداث الفلكية للأسبوع القادم، وعند إرسال birth، كل عبور على تلك الخريطة مع جانبه والأورب الخاص به، وهل هو مقترب أم متباعد، واللحظة التي يبلغ فيها الزاوية الدقيقة أو بلغها، وبيت خريطة الميلاد الذي يقع فيه الجرم العابر. وحدود الأورب للعبور 2° للقمر والشمس وعطارد والزهرة والمريخ، و3° للأجرام الأبطأ. وهناك حقلان يمثلان قاعدتين ثابتتين لا حسابًا فلكيًا، وتذكر الاستجابة ذلك: tone (supportive للتثليث والتسديس، وchallenging للتربيع والمقابلة، وintensifying للاقتران)، وfocus، وهي الصلات الثلاث الأعلى ترتيبًا حسب سرعة الكوكب ودقة الجانب. ولا يوجد نص مكتوب؛ فذلك الجزء متروك لك.

استجابة حقيقية للخريطة التوضيحية في 2026-09-18، مع اختصار القوائم إلى عنصرين:

{
  "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

ست نقاط نهاية تشمل معًا كل ما يحسبه التطبيق. وكل مثال أدناه استجابة حقيقية للخريطة التوضيحية، مختصرة؛ ويرمز "..." في الطلب إلى كائن بيانات الميلاد المعروض أعلاه.

العبور خلال فترة

تستقبل نقطة النهاية POST /v1/transits الحقول birth وfrom وto (بحد أقصى 92 يومًا)، وتُرجع حسب التاريخ كل جانب دقيق بين كوكب عابر وخريطة الميلاد، وكل دخول إلى برج، وكل توقف خلال الفترة، إضافةً إلى الصلات النشطة في اليوم الأول مع مرحلتها ولحظة بلوغها الزاوية الدقيقة.

{
  "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"
    }
  ]
}

مقارنة الخريطتين (السيناستري)

تستقبل نقطة النهاية POST /v1/synastry الحقلين personA وpersonB، وتُرجع الجوانب بين الخريطتين مع الأورب، والبيوت التي تقع فيها كواكب كل شخص في خريطة الآخر، وتقييمًا لكل مجال من مجالات الحياة الستة. والشخص الثاني هنا افتراضي أيضًا (1989-03-14، 07:45، نيويورك).

{
  "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
  }
}

العودة الشمسية

تستقبل نقطة النهاية POST /v1/solar-return الحقلين birth وyear والحقل الاختياري location، وتُرجع اللحظة الدقيقة لعودة الشمس إلى طولها البروجي في خريطة الميلاد، مع الخريطة الكاملة محسوبة لتلك اللحظة. وهي تحتاج إلى وقت الميلاد: فمن دونه يكون موقع الشمس في خريطة الميلاد غير مؤكد بمقدار نصف درجة، ما يزيح لحظة العودة نحو اثنتي عشرة ساعة.

{
  "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"
}

أفضل الأيام لنشاط معيّن

تستقبل نقطة النهاية POST /v1/timing الحقل birth، والحقل activity (general، business، romance، health، creative، travel، home أو clarity)، والحقلين from وto (بحد أقصى 62 يومًا)، والحقل الاختياري timezone الذي يحدد موعد بداية كل يوم. ويُقيَّم كل يوم من 0 إلى 100 بناءً على هندسة العبور الدقيقة، مع ترجيح الكواكب المهمة لذلك النشاط، وتأتي أفضل خمسة أيام أولًا. إنها تصف السماء، ولا تَعِد بما سيكون عليه اليوم.

{
  "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°)"
      ]
    }
  ]
}

مكان مقابل خريطة

تستقبل نقطة النهاية POST /v1/locations/score الحقل birth والحقل location متضمنًا الإحداثيات. تُنقل الخريطة إلى ذلك المكان، وتُعطي الاستجابة أوتاد خريطة الانتقال، والكواكب الواقعة عليها مع الأورب، وتقييمًا من 0 إلى 10 لكل مجال من مجالات الحياة (5 تعني الحياد)، ومدى قوة تفاعل الخريطة مع المكان أصلًا: قوي حين يقع كوكب رئيسي في حدود 2° من أحد الأوتاد، ومتوسط في حدود 4°، وضعيف فيما عدا ذلك.

{
  "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"
}

أفضل المدن لخريطة معيّنة

تستقبل نقطة النهاية POST /v1/locations/rank الحقل birth، والحقل الاختياري focus (أيٌّ من identity، love، body، money، home، mind)، والحقل الاختياري region، والحقل limit بقيمة من 3 إلى 12، وترتّب فهرسًا يضم 61 من المدن الكبرى. ولا تشمل المقارنة كل مدن العالم؛ إذ يمكن تقييم أي مكان آخر بنقطة النهاية السابقة.

{
  "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°"
      ]
    }
  ]
}

الحدود والأسعار

تُحتسب الطلبات لكل حساب، عبر جميع مفاتيحه، وتتجدد الحصة عند الساعة 00:00 بتوقيت UTC. وتحمل كل استجابة الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. ولا يُحتسب الطلب المرفوض لعدم صلاحيته، والحساب الذي يفشل بسبب خطأ من جهتنا يُردّ إلى الحصة، والطلب GET /v1/usage مجاني دائمًا. واشتراك API Pro منفصل عن باقات التطبيق: فهو لا يشمل باقة Premium في التطبيق، ولا تشمله باقة Premium. والحصتان منفصلتان كذلك: يحسب التطبيق إجابات الذكاء الاصطناعي أسبوعيًا، وتحسب واجهة API هذه الحسابات باليوم وفق توقيت UTC، ولا تستهلك إحداهما من الأخرى.

الأخطاء

لكل الأخطاء شكل واحد: ‎{ "error": { "code", "message", "details"?, "docs" } }‎.

إعدادات الحساب

هذه الإعدادات ثابتة، وهي إعدادات التطبيق نفسه، موصوفة بالتفصيل في صفحة التحقق من خريطتك، ومُتحقَّق منها بمقارنتها مع NASA JPL Horizons في تقرير الدقة. ملفات بيانات Swiss Ephemeris مع تفعيل مؤشر السرعة. دائرة البروج المدارية، ومواقع مركزية أرضية ظاهرية. بيوت بلاسيدوس. العقدة القمرية الحقيقية. ليليث بوصفها الأوج القمري اللحظي. سهم السعادة بمعادلة الطالع + القمر − الشمس للخرائط النهارية والليلية على السواء. الجوانب الرئيسية الخمسة فقط: الاقتران 8°، التسديس 6°، التربيع 8°، التثليث 8°، المقابلة 8°. ويذكر كل جانب في خريطة الميلاد أو في العبور هل هو مقترب أم متباعد، استنادًا إلى سرعتي الجرمين، بما في ذلك التراجع.

الخصوصية

بيانات الميلاد بيانات شخصية. تقرؤها واجهة API، وتحسب، وتجيب، ثم تنساها: لا يُخزَّن أي جسم طلب، ولا يُستخدم شيء من البيانات المرسلة إلا لإعداد الاستجابة. وما نحتفظ به لكل طلب هو نقطة النهاية ورمز الحالة وزمن الاستجابة. والتفاصيل في سياسة الخصوصية.

أسئلة وأجوبة