المرجع

مرجع Hyz API

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

عنوان الأساس

يذهب كل استدعاء إلى عنوان الأساس هذا مع إضافة مقطع الأداة نفسها — وهو الجزء الأخير من كل مسار معروض أدناه. وأمثلة curl تحمل العنوان كاملًا جاهزًا للّصق.

https://haiyz.net/api/enterprise/v1/gis

كل نقطة نهاية موثّقة هنا هي POST، وكل واحدة منها تحمل مدخلاتها في جسم الطلب.
أدوات الملفات تستقبل حقول multipart تمامًا كما ترسلها أدوات التطبيق، أما نقطة نهاية إعادة الإسقاط بـ JSON فهي وحدها التي تستقبل جسم JSON.
عبر HTTPS فقط، وبيانات الاعتماد تُرسل في الترويسات — لا في سلسلة الاستعلام حيث تحتفظ بها الوسائط وسجلات الوصول.

غلاف الاستجابة

تستخدم الاستجابات غلاف المنصة القياسي: الحقل ok يبيّن ما إذا نجح الاستدعاء، و code معرّف ثابت يقرؤه الحاسوب، و message نص موجّه للإنسان، و data يحمل نتيجة الأداة نفسها.

{
  "ok": true,
  "statusCode": 200,
  "code": "SUCCESS",
  "data": {
    "key": "gis/2026/08/… .geojson",
    "inputKey": "gis/2026/08/… .zip",
    "filename": "parcels.geojson"
  },
  "path": "/enterprise/v1/gis/validate-convert",
  "method": "POST",
  "timestamp": "2026-08-17T09:41:22.104Z"
}

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

التوثيق

أرسل بيانات اعتمادك كترويسات في كل طلب:

X-Api-Key — مفتاحك العام (يبدأ بـ haiyz_pk_).
X-Api-Secret — مفتاحك السري (يبدأ بـ haiyz_sk_).
X-Api-User — اختياري؛ بريد العضو المعيّن لنسب الاستدعاء إليه. الافتراضي هو مالك المؤسسة.

Authorization: Bearer

يمكن استبدال زوج الترويسات بترويسة Authorization واحدة تحمل المفتاح العام والمفتاح السري وبينهما نقطتان رأسيتان. والتوثيق متطابق في الحالتين، فاختر ما يسهل ضبطه في عميلك.

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \
  -H "Authorization: Bearer haiyz_pk_live_xxxxxxxxxxxx:haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "target_format=geojson"

احتفظ بالمفتاح السري في الخادم

يُقارَن المفتاح السري بزمن ثابت ويُخزَّن مجزّأً، ولذلك لا يمكن عرضه عليك بعد الإنشاء. مكانه متغيّر بيئة في الخادم — لا في كود المتصفح ولا في حزمة تطبيق جوال ولا في مستودع كود. وإن تسرّب مفتاح، أنشئ بديلًا وأبطل القديم؛ فلا يوجد تدوير في المكان.

نسب التشغيل

أي عضو في مؤسستك يعود إليه التشغيل.

إن أهملت ترويسة X-Api-User، نُسب التشغيل إلى مالك المؤسسة.
يجب أن يعود البريد الذي ترسله إلى عضو فعّال في المؤسسة، وما عدا ذلك يُرفض بالرمز ENTERPRISE_API_USER_NOT_ASSIGNED.
يُسجَّل التشغيل بوصفه عمل ذلك العضو: يظهر المخرج المخزّن وسجل الاستهلاك في سجله داخل التطبيق، تمامًا كما لو شغّل الأداة بنفسه هناك.
وبالتوازي يسجّل سجل المؤسسة الملفات التي استهلكها التشغيل، لكل مفتاح ولكل نافذة — وعليه تُبنى تفصيلات الاستهلاك في لوحة التحكم.

نقاط النهاية

جميع النقاط POST ضمن ‎/enterprise/v1/gis‎. أجسام الطلب والاستجابة مطابقة لأدوات GIS في التطبيق.

يعرض كل قسم أدناه عقد الاتصال: الحقول التي يحملها الطلب، وما الذي يعود، ومثال curl يمكنك لصقه بعد استبدال بيانات الاعتماد التجريبية.

POST/enterprise/v1/gis/validate-convert

التحقق والتحويل

تحقّق من ملف Shapefile أو GeoJSON أو KML وحوّله

يقرأ الملف المتجهي المرفوع، ويتأكد من سلامة بنيته، ثم يكتبه بالصيغة التي طلبتها. وهذه أول ما يستدعيه خط الاستقبال، لتفترض كل المراحل اللاحقة صيغة واحدة.

الطلبmultipart/form-data

filefileمطلوب: ملف الإدخال. ملف متجهي واحد لكل طلب — Shapefile مضغوط أو GeoJSON أو KML.
target_formatstringمطلوب: الصيغة التي يُكتب بها المخرج، مثل geojson.

الاستجابة

تعيد مفتاح تخزين الملف المحوّل، ومفتاح المدخل الذي أُنتج منه، واسم ملف المخرج.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "target_format=geojson"

POST/enterprise/v1/gis/transform-crs/json

إعادة إسقاط الإحداثيات (JSON)

أعد إسقاط أزواج الإحداثيات (مدخل ومخرج JSON)

تأخذ أزواج الإحداثيات في جسم الطلب وتعيدها في نظام الإحداثيات الهدف. ولا تنتج ملفًا، ولذلك فهي أخف استدعاء على هذا السطح: تُحتسب بملف واحد على النافذة مهما بلغ عدد النقاط.

الطلبapplication/json

source_crsstringمطلوب: نظام الإحداثيات الذي عليه المدخل، برمز EPSG — مثل EPSG:4326.
target_crsstringمطلوب: نظام الإحداثيات المطلوب إنتاجه، برمز EPSG — مثل EPSG:3857.
pointsarrayمطلوب: أزواج الإحداثيات المراد إعادة إسقاطها، كمصفوفة كائنات تحمل x و y.

الاستجابة

تعيد الأزواج بعد إعادة إسقاطها بالترتيب نفسه الذي أُرسلت به، في transformedPoints.

transformedPoints

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/json \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Api-User: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "source_crs": "EPSG:4326",
    "target_crs": "EPSG:3857",
    "points": [{ "x": 46.72, "y": 24.68 }]
  }'

POST/enterprise/v1/gis/transform-crs/csv

إعادة إسقاط ملف CSV

أعد إسقاط ملف CSV من الإحداثيات

إعادة الإسقاط نفسها لملف إحداثيات: ارفع ملف CSV، وحدّد نظامي الإحداثيات، فيُكتب ملف CSV محوّل.

الطلبmultipart/form-data

filefileمطلوب: ملف الإدخال. ملف متجهي واحد لكل طلب — Shapefile مضغوط أو GeoJSON أو KML.
source_crsstringمطلوب: نظام الإحداثيات الذي عليه المدخل، برمز EPSG — مثل EPSG:4326.
target_crsstringمطلوب: نظام الإحداثيات المطلوب إنتاجه، برمز EPSG — مثل EPSG:3857.

الاستجابة

تعيد مفتاحي تخزين المخرج والمدخل، واسم ملف المخرج، وعدد النقاط التي حُوّلت.

key
inputKey
outputFilename
pointCount

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/csv \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "source_crs=EPSG:4326" \
  -F "target_crs=EPSG:32638"

POST/enterprise/v1/gis/buffer

إنشاء نطاق

أنشئ نطاقًا حول الأشكال الهندسية بمسافة محدّدة

يوسّع كل شكل هندسي في الملف بمسافة بالأمتار — نطاقات حماية، وارتدادات، وحلقات تغذية. فعّل dissolve حين يجب أن تصبح الحلقات المتداخلة مساحة واحدة بدل عدة مساحات.

الطلبmultipart/form-data

filefileمطلوب: ملف الإدخال. ملف متجهي واحد لكل طلب — Shapefile مضغوط أو GeoJSON أو KML.
distance_mnumberمطلوب: مسافة النطاق بالأمتار.
target_formatstringمطلوب: الصيغة التي يُكتب بها المخرج، مثل geojson.
dissolvebooleanاختياري: دمج النطاقات المتداخلة في شكل هندسي واحد بدل الإبقاء على نطاق لكل معلم.

الاستجابة

تعيد مفتاح تخزين ملف النطاقات، ومفتاح المدخل، واسم ملف المخرج.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/buffer \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "distance_m=100" \
  -F "target_format=geojson" \
  -F "dissolve=false"

POST/enterprise/v1/gis/merge

الدمج

ادمج عدة ملفات متجهية

تجمع عدة ملفات متجهية في ملف واحد. وهذا هو الاستدعاء المناسب للبيانات التي تصل مقسّمة حسب الحي أو اللوحة أو المقاول بينما تتوقع المراحل اللاحقة طبقة واحدة.

الطلبmultipart/form-data

filesfileمطلوب: ملفات الإدخال.كرّر الحقل مرة لكل ملف.
target_formatstringمطلوب: الصيغة التي يُكتب بها المخرج، مثل geojson.

الاستجابة

تعيد مفتاح تخزين الملف المدموج واسم ملفه.

key
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/merge \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "target_format=geojson"

POST/enterprise/v1/gis/simplify

التبسيط

بسّط الأشكال الهندسية وفق حد تفاوت

تقلّل عدد الرؤوس وفق حد تفاوت — وهو الاستدعاء الذي يجعل طبقة حدود ثقيلة قابلة للاستخدام على الويب. أبقِ preserve_topology مفعّلًا ما لم تكن التقاطعات الذاتية مقبولة في المخرج.

الطلبmultipart/form-data

filefileمطلوب: ملف الإدخال. ملف متجهي واحد لكل طلب — Shapefile مضغوط أو GeoJSON أو KML.
tolerancenumberمطلوب: حد التبسيط، معبّرًا عنه بوحدات نظام الإحداثيات الخاص بالبيانات نفسها.
target_formatstringمطلوب: الصيغة التي يُكتب بها المخرج، مثل geojson.
preserve_topologybooleanاختياري: الإبقاء على صلاحية الأشكال الهندسية أثناء التبسيط، مقابل تقليل أقل قليلًا.

الاستجابة

تعيد مفتاح تخزين الملف المبسّط، ومفتاح المدخل، واسم ملف المخرج.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/simplify \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "tolerance=0.001" \
  -F "target_format=geojson" \
  -F "preserve_topology=true"

POST/enterprise/v1/gis/extract-exif

استخراج GPS من الصور

استخرج بيانات GPS من الصور إلى GeoJSON

تقرأ بيانات EXIF من صور JPEG المرفوعة وتحوّل ما تجده من إحداثيات GPS إلى نقاط. والصور التي لا تحمل موقعًا يُبلَّغ عنها بدل إسقاطها، ليرى الفريق الميداني الصور التي تحتاج إلى معالجة.

الطلبmultipart/form-data

filesfileمطلوب: ملفات الإدخال.كرّر الحقل مرة لكل ملف.

الاستجابة

تعيد صفًا لكل صورة — اسم الملف، وهل حملت GPS، وخط العرض وخط الطول والارتفاع والتوقيت — إضافة إلى عدد الصور الموسومة وإجمالي الصور ومفتاح ملف GeoJSON المنتَج.

images
geotaggedCount
totalCount
geojsonOutput

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/extract-exif \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "[email protected]"

الأخطاء والحدود والحصص

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

افتح الأخطاء والحدود