NatalChart.AI

للمطورين

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

حسابات التنجيم بصيغة JSON، تُجرى بمكتبة Swiss Ephemeris: المحرك نفسه الذي يرسم كل خريطة في NatalChart.AI، من دون طبقة التفسير. لا استدعاءات للذكاء الاصطناعي، لذا تعيد المدخلات نفسها الأرقام نفسها دائمًا.

✦ Swiss Ephemeris✦ 10 طلبات يوميًا مجانًا✦ لا تُخزَّن أجسام الطلبات أبدًا

آخر تحديث: · المراجعة التالية:

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

بداية سريعة

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

أمثلة على الشيفرة

الطلب نفسه بلغات JavaScript وPython وPHP. ويصلح أي عميل HTTP، ويتيح مستند OpenAPI لمولّد الشيفرة أن يكتب العميل بدلًا منك.

JavaScript

const res = await fetch("https://api.natalchart.ai/v1/chart/short", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NATALCHART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ birth: { date: "1991-09-06", time: "18:30", latitude: 50.4501, longitude: 30.5234 } }),
});
const chart = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.natalchart.ai/v1/chart/short",
    headers={"Authorization": f"Bearer {os.environ['NATALCHART_API_KEY']}"},
    json={"birth": {"date": "1991-09-06", "time": "18:30", "latitude": 50.4501, "longitude": 30.5234}},
)
chart = res.json()

PHP

$ch = curl_init("https://api.natalchart.ai/v1/chart/short");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("NATALCHART_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["birth" => ["date" => "1991-09-06", "time" => "18:30", "latitude" => 50.4501, "longitude" => 30.5234]]),
]);
$chart = json_decode(curl_exec($ch), true);

خادم 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"
  }
}
الحقلإلزاميالمعنى
dateنعمتاريخ الميلاد بصيغة YYYY-MM-DD، من 1800 إلى 2399.
timeلاالتوقيت المحلي بصيغة HH:mm، بنظام 24 ساعة. والقيمة null إذا كان غير معروف.
latitude, longitudeنعمبالدرجات العشرية، والقيم موجبة للشمال والشرق.
timezoneلامنطقة زمنية بمعيار IANA. وإذا أُغفلت، تُحدَّد من الإحداثيات وفق قواعد التوقيت الصيفي في ذلك التاريخ.

نقاط النهاية

نقطة النهايةالباقةما تُرجعه
POST /v1/chart/shortالباقة المجانيةالخريطة المختصرة: الشمس والقمر والطالع مع درجاتها، وبرج كل جرم، والأجرام المتراجعة، والعنصر والنمط الغالبان.
POST /v1/chart/fullالباقة المجانيةالخريطة الكاملة: كل جرم مع طوله البروجي وبرجه ودرجته وسرعته ومؤشر تراجعه وبيته؛ والأوتاد؛ ورؤوس البيوت الاثنا عشر بنظام بلاسيدوس؛ والجوانب مع الأورب؛ وتوازن العناصر والأنماط؛ والاقترانات مع النجوم الثابتة.
POST /v1/chart/planetsالباقة المجانيةالأجرام فقط: الطول البروجي، والبرج، والدرجة داخل البرج، والسرعة اليومية، ومؤشر التراجع، والبيت.
POST /v1/chart/anglesالباقة المجانيةالطالع ووسط السماء والفيرتكس وسهم السعادة.
POST /v1/chart/housesالباقة المجانيةرؤوس البيوت الاثنا عشر بنظام بلاسيدوس.
POST /v1/chart/aspectsالباقة المجانيةالجوانب الرئيسية الخمسة بين الأجرام، مع زاوية كل جانب والأورب الخاص به، وجدول الأورب المستخدم.
POST /v1/chart/elementsالباقة المجانيةتوازن العناصر والأنماط، مع الغالب في كل منهما.
POST /v1/chart/fixed-starsالباقة المجانيةاقترانات النجوم الثابتة بأجرام خريطة الميلاد في حدود 1.5 درجة.
POST /v1/horoscope/dailyالباقة المجانيةاليوم محسوبًا: السماء عند الظهر بتوقيت UTC، وطور القمر، والأحداث الفلكية للأسبوع القادم، ومع بيانات الميلاد، كل عبور على خريطة الميلاد مع الأورب الخاص به. بلا نص مولَّد.
GET /v1/skyالباقة المجانيةمواقع الكواكب وطور القمر والأحداث الفلكية للأسبوع القادم لتاريخ معيّن (‎?date=YYYY-MM-DD، واليوم افتراضيًا). يعمل دون مفتاح.
GET /v1/usageالباقة المجانيةباقتك، وعدد طلبات اليوم، وموعد تجدد الحصة. بلا تكلفة.
POST /v1/transitsPremium وMAXحتى 60 حدثًا من أحداث العبور في فترة تصل إلى 92 يومًا، مع الإبقاء على الأهم إذا كانت الأحداث أكثر: الجوانب الدقيقة بين الكواكب العابرة وخريطة الميلاد حسب التاريخ، ودخول الكواكب إلى الأبراج، والتوقفات.
POST /v1/synastryPremium وMAXمقارنة خريطتين: الجوانب بين الخريطتين مع الأورب، وتراكب البيوت في الاتجاهين، وتقييم لكل مجال من مجالات الحياة.
POST /v1/solar-returnPremium وMAXخريطة العودة الشمسية لسنة معيّنة، محسوبة لمكان الميلاد أو لمكان آخر.
POST /v1/timingPremium وMAXكل يوم في فترة تصل إلى 62 يومًا، مقيَّمًا لنشاط واحد (general، business، romance، health، creative، travel، home، clarity): العبور الداعم والمعيق، وطور القمر وبرجه، وخلوّ القمر من المسار. وأفضل خمسة أيام أولًا.
POST /v1/locations/scorePremium وMAXمكان واحد مقابل خريطة واحدة: أوتاد خريطة الانتقال، والكواكب الواقعة عليها مع الأورب، وتقييم لكل مجال من مجالات الحياة، وتقييم إجمالي.
POST /v1/locations/rankPremium وMAXفهرس المدن الكبرى مرتَّبًا لخريطة واحدة، إجمالًا أو حسب مجالات حياة مختارة، على مستوى العالم أو في منطقة واحدة.

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

تُرجع نقطة النهاية 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"
    }
  ]
}

نقاط النهاية في باقتي Premium وMAX

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

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

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

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "at": "2026-09-19T10:10:33.151Z",
      "date": "2026-09-19",
      "position": "14°06′ Libra",
      "house": 8,
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "targetPosition": "14°06′ Capricorn",
      "targetHouse": 11,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-22T09:53:49.800Z",
      "date": "2026-09-22",
      "position": "18°00′ Leo",
      "house": 7,
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "targetPosition": "18°00′ Scorpio",
      "targetHouse": 8,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-23T20:47:58.234Z",
      "date": "2026-09-23",
      "position": "0°51′ Libra",
      "house": 7,
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "targetPosition": "0°51′ Aquarius",
      "targetHouse": 12,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-26T12:58:36.996Z",
      "date": "2026-09-26",
      "position": "3°28′ Libra",
      "house": 7,
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "targetPosition": "3°28′ Libra",
      "targetHouse": 7,
      "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°"
      ]
    }
  ]
}

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

الباقةالسعرالطلباتنقاط النهاية
الباقة المجانية$010 يوميًاالخرائط وأجزاؤها، والأبراج اليومية، والسماء
Premium$9.99 شهريًا أو $79 سنويًا100 يوميًاكل شيء: العبور، ومقارنة الخريطتين، والعودة الشمسية، وأفضل الأيام، والأماكن
MAX$19.99 شهريًا أو $179 سنويًابلا حد يوميكل شيء: العبور، ومقارنة الخريطتين، والعودة الشمسية، وأفضل الأيام، والأماكن

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

الأخطاء

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

الحالةالرمزمتى
400invalid_requestجسم الطلب غير صالح. ويسرد الحقل details كل المشكلات. لا يُحتسب.
401missing_api_key, invalid_api_keyلا يوجد مفتاح، أو المفتاح غير معروف، أو مُبطَل.
403plan_requiredاستدعاء نقطة نهاية خاصة بباقتي Premium وMAX على الباقة المجانية.
429daily_limit_reachedاستُنفدت حصة اليوم. وتتجدد عند الساعة 00:00 بتوقيت UTC.
500internal_errorخطأ من جهتنا. ولا يُحتسب الطلب.

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

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

في بيئة الإنتاج

خلال آخر 30 يومًا (من 19 سبتمبر 2026 إلى 16 أكتوبر 2026)، أجاب الخادم عن طلب الحساب في 280 ملّي ثانية بالقيمة الوسيطة، وفي 526 ملّي ثانية عند المئين 95، والزمن مقيس من لحظة وصول الطلب إلى لحظة خروج الاستجابة. ويقارن تقرير الدقة أرقام خريطة اختبار منشورة واحدة مع NASA JPL Horizons.

الخصوصية

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

سجل التغييرات

  • 2 نوفمبر 2026: أصبحت واجهة API وخادم MCP ضمن باقات تطبيق NatalChart.AI: جميع نقاط النهاية في Premium بمعدل 100 طلب يوميًا، وفي MAX بلا حد يومي. وانتقلت المفاتيح إلى التطبيق، في تبويب API & MCP ضمن الإعدادات.
  • 16 أكتوبر 2026: تذكر الاستجابتان 429 و403 السعر، وتحملان الحقل upgrade_url مع رابط الترقية.
  • 3 أكتوبر 2026: تستخدم تقييمات الأماكن النموذج نفسه المستخدم في تطبيق NatalChart.AI، وتضيف نقطة النهاية /v1/locations/score الحقل overall10.
  • 2 أكتوبر 2026: أُطلق خادم MCP على https://www.natalchart.ai/mcp، وهو مُدرج في السجل الرسمي MCP Registry.
  • 22 سبتمبر 2026: تُقبل المفاتيح مجردةً، أو بين علامتي تنصيص، أو مع تكرار كلمة Bearer، ويوضح كل رد 401 سبب الخطأ.
  • 19 سبتمبر 2026: انضمت إلى واجهة API نقطة نهاية أفضل الأيام ونقطتا النهاية الخاصتان بالأماكن: سبع عشرة نقطة نهاية في المجموع.
  • 18 سبتمبر 2026: أُطلقت واجهة API: الخرائط الفلكية والأبراج اليومية والسماء بمفتاح مجاني؛ والعبور ومقارنة الخريطتين والعودة الشمسية في باقة مدفوعة.

أسئلة وأجوبة

هل تستخدم واجهة API الذكاء الاصطناعي؟

لا. كل نقطة نهاية عملية حسابية: مواقع الكواكب من مكتبة Swiss Ephemeris، ورؤوس البيوت، والجوانب، والعبور. لا يُولَّد أي نص ولا يُستدعى أي نموذج لغوي، ولهذا تعيد المدخلات نفسها دائمًا الأرقام نفسها.

هل يمكنني اختيار نظام البيوت أو دائرة البروج النجمية؟

لا. كل خريطة محسوبة على دائرة البروج المدارية ببيوت بلاسيدوس، وهي الإعدادات نفسها التي يستخدمها تطبيق NatalChart.AI. وإذا لزمت بيوت البرج الكامل أو نظام كوخ أو دائرة البروج النجمية، فهذه ليست واجهة API المناسبة لذلك.

ماذا يحدث إذا كان وقت الميلاد غير معروف؟

يُرسَل الحقل time بالقيمة null. تُحسب المواقع للساعة 12:00 بالتوقيت المحلي بوصفها لحظة مفترضة، وتذكر الاستجابة ذلك في الحقل assumedLocalTime، ويُحجب ما يحتاج إلى الوقت الدقيق بدل تخمينه: تعود الأوتاد (الطالع، ووسط السماء، والفيرتكس، وسهم السعادة) ورؤوس البيوت بالقيمة null، ولا يُسند إلى الأجرام أي بيت. ويذكر تحذير أن موقع القمر قد ينحرف بما يصل إلى نحو 7.5 درجات، وقد يقع في البرج المجاور؛ وقد يختلف أيضًا في الوقت الحقيقي أي جرم أو جانب قريب من حد برج أو حد أورب.

هل تُحوَّل أسماء الأماكن إلى إحداثيات؟

لا. يُرسَل خط العرض وخط الطول. وتُحدَّد المنطقة الزمنية من الإحداثيات، وفق قواعد التوقيت الصيفي التاريخية لذلك التاريخ، ما لم تُرسَل منطقة زمنية بمعيار IANA صراحةً.

هل تُخزَّن بيانات الميلاد التي أرسلها؟

لا. لا تُكتب أجسام الطلبات في أي مكان. ويحتفظ سجل الطلبات بنقطة النهاية ورمز الحالة وزمن الاستجابة، وهذا ما يحتاج إليه عدّاد الاستخدام.

ما الذي يُحتسب طلبًا؟

استدعاء ناجح واحد لنقطة نهاية حسابية. الطلب المرفوض لعدم صلاحيته لا يكلّف شيئًا، والطلب الذي يفشل بسبب خطأ من جهتنا يُردّ إلى الحصة، والمسار ‎/v1/usage مجاني. والحصة لكل حساب لا لكل مفتاح، وتتجدد عند الساعة 00:00 بتوقيت UTC: 10 يوميًا في الباقة المجانية، و100 يوميًا في Premium، وبلا حد يومي في MAX.

هل يمكنني استخدامها في منتج تجاري؟

نعم، في جميع الباقات. ويُرجى إبقاء المفتاح على خادم: فالمفتاح الموجود في شيفرة المتصفح أو التطبيق يمكن أن ينسخه أي شخص يفتحها.

هل حان وقت رؤية خريطتك الحقيقية؟

إنشاء خريطتي المجانية