أداة جغرافية واحدة تحفظها واجهةً خاصة بك — إعداداتها ثابتة، ومدخلها الثاني أحد عناصر بياناتك — ويستدعيها نظام آخر بمفتاح خاص بها.
واجهة الأداة أداة جغرافية واحدة تُحفظ واجهةَ برمجة تطبيقات خاصة بمالكها: شخص على فئة Pro أو ماكس، أو مؤسسة. إعداداتها ثابتة، ومدخل الأداة الثاني مربوط بأحد عناصر بيانات المالك نفسه: يُقرأ مباشرة بوصفه طبقة حيّز — فيظهر التعديل في الطلب التالي — أو بوصفه ملفًا: أحدث إصدار سليم بعد الفحص عند كل طلب، أو إصدار مثبّت. ويستدعيها نظام آخر بمفتاح خاص بها، فيرسل المدخل الرئيسي وحده بصيغة GeoJSON ويقرأ الإجابة بصيغة JSON.
ومثال المالك «داخل السعودية»: فحص الاحتواء، وحدود المملكة مربوطة مرجعًا له، مع قاعدة — داخلها كليًا، أو جزئيًا، أو بنسبة لا تقل عن حدّ معيّن.
يمكن أن تُحفظ بهذه الطريقة أي أداة متجهة مدخلها الرئيسي طبقة واحدة ومخرجها طبقة: الأدوات الهندسية، وتراكب التقاطع والاتحاد، وحساب الخصائص الهندسية، والتحقق، والربط المكاني، وإحصاءات المناطق، وفحص الاحتواء. أما أدوات الراستر والصور والمستندات فلا.
والمدخل المربوط هو المدخل الثاني للأداة: طبقة القناع في القص والمحو، وطبقة التراكب في التقاطع والاتحاد، وطبقة الربط في الربط المكاني، والراستر في إحصاءات المناطق، والمرجع في فحص الاحتواء.
ميزة تجريبية
ينشئ الشخص واجهاته في البوابة، وتنشئ المؤسسة واجهاتها في مركز التحكم.
طلب واحد بمفتاح الواجهة الخاص. يرسل المستدعي المدخل الرئيسي وحده، فالإعدادات والطبقات المربوطة محفوظة سلفًا.
/tool-apis/{id}/runأضف المسار إلى العنوان الأساسي لواجهة برمجة التطبيقات، ومعرّف واجهة الأداة في موضعه:
https://haiyz.net/apiAuthorization: Bearer hyzapi_…hyzapi_. والواجهة غير المعروفة، وغياب المفتاح، والمفتاح الملغى، والمفتاح الخاطئ، كلها تتلقى الرد نفسه 401.Content-Type: application/jsoninputنقطة في الرياض تُرسل إلى واجهة أداة مبنية على فحص الاحتواء ومرجعها حدود المملكة. اجعل TOOL_API_ID معرّف الواجهة، وTOOL_API_KEY مفتاحها.
curl -X POST "https://haiyz.net/api/tool-apis/$TOOL_API_ID/run" \
-H "Authorization: Bearer $TOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"type":"Point","coordinates":[46.7,24.7]}}'يتوقف محتوى الإجابة على الأداة: الأداة الهندسية تعيد نتيجتها، وفحص الاحتواء يعيد حكمًا لكل معلم.
تأتي كل إجابة في غلاف المنصّة القياسي — ok وcode، وdata عند النجاح — ويصفه المرجع مرة واحدة. اقرأ عن الغلاف
كل أداة عدا فحص الاحتواء تجيب بنتيجتها بصيغة GeoJSON في data:
featureCountresultيجيب فحص الاحتواء بأحكامه في data:
passedcountsinside وpartial وoutside، وعدد ما اجتاز منها passed.resultsكل عنصر في results يقابل معلمًا واحدًا من المدخل:
results[].indexresults[].relationinside أو partial أو outside — انظر كيف يقرّر فحص الاحتواء أدناه.results[].percentInsideresults[].passresults[].matchCountresults[].referenceإجابة الطلب السابق: تقع النقطة داخل المرجع فتجتاز القاعدة، ويحمل reference الحقل الذي اختاره المالك من حدود المملكة.
{
"ok": true,
"statusCode": 200,
"code": "TOOL_API_RESULT",
"data": {
"passed": true,
"counts": { "inside": 1, "partial": 0, "outside": 0, "passed": 1 },
"results": [
{
"index": 0,
"relation": "inside",
"percentInside": 100,
"pass": true,
"matchCount": 1,
"reference": { "name": "Saudi Arabia" }
}
]
}
}يُقارَن كل معلم في المدخل بطبقة المضلّعات المرجعية المربوطة.
insidepartialoutsidepercentInside هي نسبة ما يقع داخل المرجع من مساحة المضلّع، أو طول الخط، أو عدد نقاط المعلم متعدد النقاط، وتُقاس في إسقاط متساوي المساحة. والنقطة إما 100 أو 0.
insidepartialpercent ≥ NpercentInside عن N.يحمل reference الحقول التي اختارها المالك من معلم المرجع الذي يتداخل معه المدخل أكثر من غيره — أي منطقة يقع فيها، مثلًا.
يُحتسب كل طلب طلبَ API واحدًا من مخصّص مالكه اليومي، لا تشغيلًا لأداة.
تُحتسب طلبات الشخص من طلبات API اليومية في خطته، وتشاركه فيها مفاتيح API الشخصية. وتُحتسب طلبات المؤسسة من طلبات API اليومية في فئتها.
الطبقات المربوطة لا تغادر المنصّة
ما يحتفظ به المالك
الرموز التي قد يجيب بها الطلب، ومعنى كل منها.
TOOL_API_INPUT_INVALIDالمدخل ليس كائن GeoJSON صالحًا من نوع Feature أو FeatureCollection أو شكلًا هندسيًا، وتبيّن الرسالة السبب.
TOOL_API_KEY_INVALIDالواجهة غير معروفة، أو المفتاح غائب أو ملغى أو خاطئ. والحالات الأربع تتلقى الرد نفسه.
TOOL_API_DISABLEDأوقف المالك تشغيل واجهة الأداة هذه.
TOOL_API_PLANلم يعد المالك على خطة أو فئة تشمل واجهات الأدوات، وتعود الواجهة إلى الإجابة حين يعود إليها.
TOOL_API_SUSPENDEDحساب المالك أو مؤسسته موقوف، ولا تُجيب الواجهة عن أي طلب ما دام موقوفًا.
TOOL_API_HELDأوقفت حيّز واجهة الأداة هذه، ولا تُجيب عن أي طلب حتى ترفع حيّز الإيقاف، ويُبلَّغ مالكها بالسبب.
GIS_TIER_REQUIREDتتطلب الأداة فئة أعلى مما لدى المالك الآن (الربط المكاني وإحصاءات المناطق تتطلبان Pro).
TOOL_API_BINDING_MISSINGعنصر بيانات مربوط بالواجهة لم يعد موجودًا، أو لم يعد ملكًا للمالك، أو ليس له إصدار سليم.
TOOL_API_INPUT_TOO_LARGEفي المدخل أكثر من 10,000 معلم.
TOOL_API_RESULT_TOO_LARGEالنتيجة أكبر من أن تُعاد في طلب واحد. أرسل معالم أقل.
API_KEY_QUOTAالمالك شخص استنفد طلبات API اليومية التي تتيحها خطته، وهي مشتركة مع مفاتيح API الشخصية.
ENTERPRISE_API_DAILY_LIMITالمالك مؤسسة استنفدت طلبات API اليومية في فئتها.
TOOL_API_RATE_LIMITEDأكثر من 60 طلبًا في الدقيقة على واجهة الأداة هذه. انتظر دقيقة ثم أعد المحاولة.
في صفحة الأخطاء الفهرس الكامل للرموز، وسياسة إعادة المحاولة لكل نوع من الإخفاق.
الأخطاء والحدود والحصص