ترميز عناوين Alkax Grid وفكها

تمنح Alkax Grid v1 الإحداثي مرجع خلية موجزاً وحتمياً. يبلغ طول كل خلية الاسمي خمسة أمتار. يشير عنوان Grid إلى خلية مكانية؛ ولا يمثل مكاناً مسجلاً في Alkax أو معرّف مكان أو إثبات ملكية أو دليلاً على وجود مكان هناك. ويعمل فك الترميز للخلايا غير المأهولة أيضاً.

التنسيق الأساسي هو CC-XXYY-LLLLL: نطاق بلد من حرفين، وأربعة أحرف للمنطقة، وخمسة أحرف للخلية المحلية. يستخدم الرمز الأبجدية 23456789CFGHJMPQRVWX. تغطي v1 عدد 55 نطاقاً لبلدان أفريقية. أصولها ثابتة؛ قد تؤثر تغييرات بيانات الحدود على البلد الذي يُسند إليه الإحداثي عند ترميزه، لكنها لا تنقل إطار v1 منشوراً. الحدود بيانات مرجعية خرائطية وليست حدوداً مساحية دقيقة.

في تطبيق Alkax

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

المصادقة والحصة

تتطلب العمليتان بيانات اعتماد المطور على الخادم في X-Alkax-Key مع النطاق places:read. وهما متاحتان لبيانات اعتماد Sandbox وProduction. احتفظ بالسر على خادمك ولا تكشفه في شيفرة المتصفح. تُحتسب الطلبات ضمن حصة واجهة المطور الشهرية العادية وحدود معدل الطلب؛ ولا توجد حصة Grid منفصلة. راجع دليل منصة المطور ودليل المصادقة. قبل تنفيذ أي من الطلبين، عيّن ALKAX_KEY إلى مفتاح Sandbox أو Production الخاص بك:

export ALKAX_KEY="ak_test_<key-id>.<secret>"

ترميز الإحداثيات

أرسل خط العرض وخط الطول كرقمين في JSON. يجب أن يكون خط العرض بين -90 و90، وخط الطول بين -180 و180:

curl "https://api.alkax.io/api/v1/addresses/grid/encode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"latitude":-1.2921,"longitude":36.8219}'

نيروبي متجه مرجعي منشور. وتكون الاستجابة:

{
  "version": 1,
  "canonicalAddress": "KE-3R43-XMWRR",
  "countryCode": "KE",
  "centerLatitude": -1.2920930818547325,
  "centerLongitude": 36.82189788797723,
  "cellSizeMetres": 5
}

يحدد الترميز البلد أولاً باستخدام هندسة الحدود المهيأة، ثم يستخدم الإطار الثابت لذلك البلد. تعيد العملية 422 إذا كان الإحداثي خارج هندسة بلد مدعوم أو خارج إطار v1 المقابل. وتعيد 503 إذا تعذر تحميل هندسة الحدود.

فك عنوان أساسي

أرسل العنوان في JSON. يفك هذا الطلب المتجه المنشور نفسه ويعيد مركز خليته:

curl "https://api.alkax.io/api/v1/addresses/grid/decode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"address":"KE-3R43-XMWRR"}'

يستخدم فك الترميز سجل إطارات v1 الثابت، ولا يحمّل هندسة البلدان أو يتحقق من وجود مكان في الخلية. تُقبل الأحرف الصغيرة والمسافات المحيطة وتُوحّد في canonicalAddress. تقبل الخدمة سلسلة عنوان بطول يصل إلى 32 حرفاً قبل التحقق من التنسيق؛ ويكون الخرج الأساسي دائماً 13 حرفاً.

عناوين Grid في استجابات الأماكن

عندما يقع الإحداثي ضمن تغطية v1، تتضمن استجابات قراءة الأماكن والبحث فيها وإنشائها وتحديثها الأساسية كائن gridAddress في المستوى الأعلى. وتكون قيمته null عندما يتعذر إسناد الإحداثي إلى إطار مدعوم. مثلاً، تتضمن الاستجابة:

{
  "id": "<registered-place-uuid>",
  "plusCode": "<registered-place-plus-code>",
  "gridAddress": {
    "version": 1,
    "canonicalAddress": "KE-3R43-XMWRR",
    "countryCode": "KE",
    "centerLatitude": -1.2920930818547325,
    "centerLongitude": 36.82189788797723,
    "cellSizeMetres": 5
  }
}

تتضمن استجابات GET /api/v1/addresses/{plusCode} وPOST /api/v1/addresses/verify الموجزة أيضاً gridAddress قابلاً لأن تكون قيمته null في المستوى الأعلى. وتضعه استجابة جواز العنوان العام داخل geography.gridAddress. هذه رموز تعريف مختلفة: يعرّف id مكاناً مسجلاً، ويعرّف plusCode رمز Plus Code الحالي، ويعرّف gridAddress.canonicalAddress خلية v1. ولا تضمن خلية Grid تسجيل مكان Alkax فيها.

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

تستخدم أخطاء الخدمة كائن الاستجابة القياسي الذي يتضمن code وmessage ومصفوفة errors. ويتضمن كل تفصيل في المصفوفة الحقول code وdescription وseverity. أما أخطاء التحقق من جسم الطلب فتعيد مصفوفة من أخطاء التحقق بدلاً من ذلك.

الحالة	سببها
400	تعيد الإحداثيات المفقودة أو الخارجة عن النطاق مصفوفة أخطاء التحقق. ويفشل العنوان الفارغ أو الذي يتجاوز 32 حرفاً في التحقق من الطلب أيضاً. أما العنوان غير السليم أو النطاق غير المدعوم أو قيمة الرمز غير المستخدمة فتعيد AddressGridInvalidRequest ضمن كائن الخطأ القياسي.
422	إحداثي الترميز خارج هندسة بلد مدعوم أو إطار v1 (AddressGridOutsideCoverage)
503	هندسة البلدان غير متاحة للترميز (AddressGridGeometryUnavailable)
401	بيانات اعتماد المطور مفقودة أو غير صالحة
403	بيانات الاعتماد لا تملك النطاق places:read
402	اشتراك Production غير نشط أو لا يتيح الوصول إلى Production
429	نفاد حصة طلبات المشروع أو الاشتراك، أو بلوغ حد معدل الطلب

مثلاً، تكون استجابة الخروج عن التغطية بهذا الشكل:

{
  "code": "AddressGridOutsideCoverage",
  "message": "The coordinate is outside Alkax Grid v1 coverage.",
  "errors": [
    {
      "code": "AddressGridOutsideCoverage",
      "description": "The coordinate is outside Alkax Grid v1 coverage.",
      "severity": "Error"
    }
  ]
}

تعتمد encode وحدها على هندسة البلدان. وقد تعيد عملية decode الحالة 400 عند إدخال غير صالح، لكنها لا تعيد 422 أو 503 بسبب التغطية الهندسية. حدود البلدان بيانات مرجعية خرائطية وليست حدوداً مساحية دقيقة؛ وقد لا تُسند الإحداثيات الواقعة على حدود المضلع. راجع مرجع API لمخططات نقاط النهاية المنشورة.