تنسيقات الحقول
النموذج اللي يخمن اسم الحقل يحصل إما على 400 أو، الأسوأ، رد مؤكد ببطاقة مختلفة. أدناه العقد الدقيق.
جسم طلب الخريطة
Section titled “جسم طلب الخريطة”| حقل | النوع والتنسيق | إلزامي |
|---|---|---|
date | YYYY-MM-DD، ويجب أن يكون تاريخًا حقيقيًا في التقويم | نعم |
time | HH:mm:ss | نعم، أو timeUnknown: true |
timezoneOffset | عدد، ساعات من UTC، مثال 5.75 | لا، الافتراضي 0 (UTC) |
timezone | اسم منطقة IANA، مثال Europe/Kyiv، أو auto | لا، وعند الإرسال، يستبدل timezoneOffset |
latitude | درجات عشرية، الشمال موجب | نعم |
longitude | درجات عشرية، الشرق موجب | نعم |
houseSystem | حرف واحد، الافتراضي P | لا |
city | نص، فقط للعلامة | لا |
zodiacType | tropical أو sidereal | لا |
الاختصارات القصيرة تُرفض
Section titled “الاختصارات القصيرة تُرفض”lat، lon، lng، long، tz، tzOffset، utcOffset، gmtOffset، timeZone، time_zone يرجعون 400 INVALID_FIELD مع اسم الحقل الصحيح:
{ "error": { "code": "INVALID_FIELD", "message": "Unsupported field \"tz\". Rename it to \"timezoneOffset\" (numeric hours from UTC, e.g. 5.75; a zone name goes in timezone)." } }الحالة وفواصل القيمة غير مسموحة: TZ_Offset و tzoffset يُرفضان بنفس الطريقة. يتم الإبلاغ عن جميع الحقول المكتشفة مرة واحدة، وليس الأول فقط، حتى يمكنك تصحيحها دفعة واحدة.
السبب صارم: قبل هذا الفحص، الحقل اللي ما قرأه الـ API كان صامتًا يعطي إزاحة 0، وكانت الاستجابة بطاقة مؤكدة للـ UTC. إزاحة ثلاث ساعات تعادل تقريبًا 45° من الصعود، أي علامة أخرى صاعدة، دون أي تحذير.
timezone: اسم المنطقة بدلًا من الإزاحة
Section titled “timezone: اسم المنطقة بدلًا من الإزاحة”الإزاحة يجب أن تكون تلك التي كانت على الساعات في ذلك التاريخ بالضبط، ومن السهل إدخالها يدويًا بشكل خاطئ: كييف في مايو 1990 كانت تتبع التوقيت الصيفي لموسكو، UTC+4، وليس +3. أرسل timezone، وسيأخذ الخادم الإزاحة من قاعدة بيانات المناطق الزمنية، بما في ذلك التوقيت الصيفي.
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv", "latitude": 50.45, "longitude": 30.52 }autoيحدد المنطقة بناءً علىlatitudeوlongitude. قرب الحدود يكون الاسم أدق.- إذا جاء
timezoneوtimezoneOffsetمعًا، يُطبقtimezone.input.timezoneOffsetفي الاستجابة يُظهر الإزاحة التي تم استخدامها. - الوقت الذي تكرر (عند إرجاع الساعات للخلف) يُؤخذ من المرة الأولى. الوقت الذي لم يحدث (عند تقديم الساعات للأمام) يحصل على الإزاحة التي كانت سارية قبل التغيير.
- بدون
time(فقط التاريخ أوtimeUnknown: true) تُقرأ المنطقة عند الظهر المحلي. - يُرفض بـ
400 INVALID_FIELD: قيمة فارغة، اختصارات مثلESTأوPST، إزاحة مكتوبة نصيًا مثل+03:00، أسماء غير موجودة في القاعدة، وautoبدون إحداثيات. يُقبلUTCوGMT. - كل كائن يُعالج بشكل منفصل، لذا يمكن أن يكون
chart1وchart2في مناطق مختلفة.
houseSystem: حرف، ليس اسم
Section titled “houseSystem: حرف، ليس اسم”يُقبل بالضبط هذه الـ 25 كودًا من Swiss Ephemeris:
P K R C E W B M O A T V D F G H I i L N Q S U X Y
الحالة مهمة: I هو Sunshine حسب ماكرانسكي، i حسب ترايندلم. اسم النظام ("Placidus"، "Koch") يُعيد 400. سابقًا كان يعمل عشوائيًا لأن المحرك يقرأ من السلسلة الحرف الأول فقط، ومن نفس السبب "Zodiac" كان صامتًا يعطي Placidus.
وقت الولادة غير معروف
Section titled “وقت الولادة غير معروف”بدلاً من الظهر المفترض، أرسل timeUnknown: true ولا ترسل time. عندها تكون houses، houseAspects، chartSect و siderealTime قيمتها null، وليس مفترضة. التفاصيل: Conventions API.
المفاتيح غير المعروفة لا تُرفض
Section titled “المفاتيح غير المعروفة لا تُرفض”الجسم يقبل الحقول الزائدة بصمت: المفتاح غير المعروف يُتجاهل ببساطة. لذلك خطأ في اسم حقل غير موجود في قائمة الرفض أعلاه لن يظهر. راجع المواصفات: /v1/openapi.json.