إمكانية إنشاء إمكانية التحقق من الموقع الجغرافي باستخدام "منصة خرائط Google"

الهدف

في كثير من الأحيان، تحتاج إلى التحقّق من صحة الموقع الجغرافي لمكان معيّن. تتوفّر بعض الخدمات المختلفة في "منصة خرائط Google" التي يمكن أن تساعدك في حالة الاستخدام هذه. يساعدك هذا المستند في الاختيار بين خدمتَي التحقّق الأساسيتَين من صحة الموقع الجغرافي، وهما Address Validation API وGeocoding API.

واجهة برمجة التطبيقات Address Validation API هي إحدى عروض "منصة خرائط Google" التي تساعد العملاء في التحقّق من صحة العناوين.

الترميز الجغرافي باستخدام Geocoding API هو عملية تحويل العناوين إلى إحداثيات جغرافية يمكنك استخدامها لوضع علامات على خريطة أو موضع على الخريطة.

يمكنك الاطّلاع على نظرة عامة عالية المستوى حول الاختلافات بين واجهة برمجة التطبيقات Address Validation API وGeocoding API هنا.

حالات استخدام Address Validation API بدلاً من Geocoding API

ملاحظات حول مخطط التدفق أعلاه:

• تشير حالة استخدام تفاعل المستخدم إلى الحالات التي يكون فيها المستخدم متواجدًا للتفاعل مع النتائج.
• ‫Places Autocomplete هي واجهة برمجة تطبيقات JavaScript، لذا فهي مناسبة للدمج مع واجهات المستخدم.
• قد تكون على دراية بمشاكل جودة البيانات في عناوينك الحالية. لذلك، على الرغم من أنّك قد تحتاج فقط إلى رموز جغرافية، ننصحك بتشغيل هذه المواقع الجغرافية من خلال Address Validation API لتصحيح مجموعات البيانات.

هناك العديد من الحالات التي قد تختار فيها، استنادًا إلى شجرة القرار أعلاه، استخدام منتج على آخر. ولكن قد تتطلّب حالات أخرى استخدام كلا المنتجين لتحقيق أهدافك.

يمكنك اختيار استخدام Address Validation API بدلاً من Geocoding API في الحالات التالية:

• هناك احتمال كبير بأن تكون البيانات مشكوكًا فيها، أو أن يؤدي الحصول على عنوان غير صحيح إلى تأثير سلبي لاحق. ويرجع ذلك إلى أنّ واجهة برمجة التطبيقات Address Validation API تقدّم المزيد من الملاحظات حول سبب عدم حصول الإدخال على نتيجة عالية الدقة.
• عليك تصحيح إدخالات المستخدمين (مثل الأخطاء الإملائية أو الحقول الناقصة)، ما يزيد من احتمال الحصول على نتيجة دقيقة.
• تعرض المنطقة المستهدَفة المزيد من البيانات الوصفية من Address Validation API مقارنةً بواجهة Geocoding API، مثل تصنيف نوع المبنى على أنّه سكني أو تجاري.

يمكنك اختيار استخدام Geocoding بدلاً من Address Validation API في الحالات التالية:

• هدفكم الأساسي هو استرداد الموقع الجغرافي لعنوان ما، وقد لا تكون دقة العناوين الفردية أمرًا بالغ الأهمية.
  • على سبيل المثال، لإنشاء خريطة حرارية من مجموعة كبيرة من البيانات.
• تحتاج إلى حلّ عالمي، ولا تتوفّر واجهة برمجة التطبيقات Address Validation API في جميع المناطق المستهدَفة.

في ما يلي بعض الأمثلة التي توضّح إمكانات Address Validation API مقارنةً بواجهة Geocoding API.

مثال على عنوان غير صالح

1 Fake St, Mountain View, CA 94043, USA

تقسّم واجهة برمجة التطبيقات Address Validation API هذا الإدخال إلى مكوّنات العنوان الفردية (الشارع والمدينة والولاية وما إلى ذلك). يمكنه أيضًا تقديم ملاحظات تفصيلية حول سبب عدم صلاحية العنوان وصولاً إلى مستوى PREMISE.

لا يتوفّر شارع Fake St في Mountain View، كاليفورنيا، وتعكس واجهة برمجة التطبيقات Address Validation API ذلك في التفاصيل التي يتم عرضها على مستوى المكوّن:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

في هذه الحالة، يجب فحص السمة المهمة confirmationLevel. من خلال عرض UNCONFIRMED_BUT_PLAUSIBLE مقابل Fake St، حدّدت واجهة برمجة التطبيقات أنّه من الممكن أن يكون هذا الاسم لشارع، ولكن لا يمكن مطابقته مع بيانات العنوان المتوفّرة.

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

باستخدام العنوان نفسه مع Geocoding API، يمكن مطابقة "كاليفورنيا" كما يظهر في لقطة الشاشة من أداة الترميز الجغرافي التي يمكنك تجربتها هنا:

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

مثال على خطأ إملائي

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

يتضمّن العنوان أعلاه خطأين إملائيين، أحدهما في اسم الشارع والآخر في المنطقة.

يمكن لواجهتَي برمجة التطبيقات Address Validation وGeocoding تصحيح هذه الأخطاء والوصول إلى النتيجة 76 Buckingham Palace Road, London, SW1W 9TQ. ومع ذلك، يمكن أن تقدّم واجهة برمجة التطبيقات Address Validation API المزيد من المعلومات عن هذه العملية.

إليك أحد عناصر العنوان التي تم إدخالها بشكل خاطئ:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

تعرض واجهة برمجة التطبيقات Address Validation API علامة للإشارة إلى أنّه تم إجراء تصحيح على الحقل. يمكن تطبيق منطق النشاط التجاري على هذا الإذن للتحقّق من التصحيح مع مقدّم البيانات، مثل عميل في صفحة الدفع في موقع للتجارة الإلكترونية.

مثال على البيانات الناقصة والخطأ الإملائي

Bollschestraße 86, 12587, DE

يتضمّن العنوان أعلاه خطأً إملائيًا في اسم الشارع، كما أنّه لا يتضمّن مدينة (موقع جغرافي) برلين.

يمكن لواجهة برمجة التطبيقات Address Validation API تصحيح كلا الخطأين وعرض رمز جغرافي بمستوى PREMISE وعنوان تم التحقّق من صحته بمستوى PREMISE:

Bölschestraße 86, 12587 Berlin, DE

لا يمكن لواجهة Geocoding API التغلّب على أخطاء الإدخال في هذه الحالة بنجاح، وتعرض النتيجة ZERO_RESULTS.

مثال على البيانات الوصفية للعنوان الإضافي

111 8th Avenue Ste 123, New York, NY 10011-5201, US

هذا العنوان صحيح باستثناء رقم الوحدة (Ste 123)، الذي لا يتوفّر في المبنى.

يمكن لواجهة برمجة التطبيقات Address Validation API التحقّق من صحة العنوان PREMISE (111 8th Ave) وتقديم بعض البيانات الوصفية حول العقار، بما في ذلك أنّه تجاري

المباني:

"business": true

بالإضافة إلى ذلك، تكون قيمة dpvConfirmation التي يتم عرضها كجزء من uspsData في الرد هي S:

"dpvConfirmation": "S"

تشير القيمة S لسمة dpvConfirmation إلى أنّه تم التحقّق من صحة العنوان على مستوى PREMISE، ولكن رقم الوحدة المقدَّم في الإدخال غير مرتبط بهذا العنوان.

لا يمكن لواجهة برمجة التطبيقات Geocoding API تقديم هذه المعلومات.

فهم الردّ من Geocoding API

نظرة عامة

إذا كنت تستخدم Geocoding API، ستحتوي نتيجة الترميز الجغرافي على أدلة مختلفة في الردّ يمكن استخدامها لفهم تفاصيل العنوان المقدَّم.

تعمل واجهة Geocoding API من خلال تحليل مكوّنات العناوين في تسلسل هرمي.

على سبيل المثال، يتم حلّ 123 Example Street, Chicago, 60007, USA بالترتيب التالي:

سيتم تقييم / Example Street/ Chicago/ 60007/ USA بهذا الترتيب. في هذه الحالة، تكون المطابقة الأولى هي شيكاغو، وتحديدًا الرمز البريدي 60007. لذلك، تعرض السمة Place_id التالية لهذا الرمز البريدي:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

تحتوي واجهة برمجة التطبيقات Geocode على المعلومات التالية في الردّ:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

يمكن لواجهة Geocoding API تأكيد نوع المكان الذي ينتمي إليه هذا العنوان. يمكن العثور هنا على قائمة بعناوين types تعرضها Geocoding API.

إذا لم يتم حلّ أي من مكوّنات الإدخال، ستعرض واجهة برمجة التطبيقات ما يلي:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

يؤدي تقديم طلب يتضمّن عنوان الشارع فقط بدون رقم المنزل إلى عرض نتيجة بالشكل التالي:

"types": [
  "route"
]

وهذا يعني أنّ Geocoding API لم يتمكّن من العثور على رقم شارع أو مطابقته.

ملاحظة: لمعرفة ما إذا كان العنوان متوفّرًا، تحقَّق ممّا إذا تم ضبط أيّ من المَعلمات (مثل types أو partial_match, results, status)) في ردّ Geocoding API. سيؤدي ذلك إلى زيادة مستوى الثقة تدريجيًا في إمكانية توفّر عنوان، ولكن لن يجعله دقيقًا بنسبة% 100. لهذا السبب نحتاج إلى واجهة برمجة التطبيقات Address Validation API.

يمكنك استخدام التقنيات المذكورة أعلاه لزيادة الثقة في دقة العنوان من ردّ Geocoding API وحده. ومع ذلك، على عكس نتيجة Address Validation API، لن تعرض Geocoding API ملاحظات دقيقة لتحديد دقة النتيجة.

نوع الموقع

لفهم هذا القسم بشكل صحيح، عليك معرفة أنواع المواقع الجغرافية المختلفة التي يمكن عرضها من رد Geocoding API:

• يشير النوع ROOFTOP إلى أنّ النتيجة التي تمّ عرضها هي رمز جغرافي دقيق يتضمّن معلومات موقع جغرافي دقيقة تصل إلى مستوى دقة عنوان الشارع.
• يشير RANGE_INTERPOLATED إلى أنّ النتيجة التي تم إرجاعها تعكس قيمة تقريبية (عادةً على طريق) تم استيفاؤها بين نقطتَين دقيقتَين (مثل التقاطعات). يتم بشكل عام عرض النتائج المُستكمَلة عندما لا تتوفّر الرموز الجغرافية الخاصة بالأسطح لعنوان شارع.
• يشير GEOMETRIC_CENTER إلى أنّ النتيجة المعروضة هي المركز الهندسي لنتيجة مثل خط متعدد الأضلاع (على سبيل المثال، شارع) أو مضلّع (منطقة).
• تشير القيمة APPROXIMATE إلى أنّ النتيجة التي تم إرجاعها لا تنطبق عليها أيّ من الحالات المذكورة أعلاه.

إذا عرضت Geocoding API location_type بقيمة ROOFTOP أو RANGE_INTERPOLATED، لا يعني ذلك بالضرورة أنّ العنوان متوفّر. وبالمثل، إذا عرضت Geocoding API النتيجة مع ضبط العلامة partial_match على true، قد تظل النتيجة مناسبة لك.

يصعب حلّ هذا النوع من المطابقة الخاطئة باستخدام Geocoding API. على الأقل، يمكنك التفكير في تنفيذ بعض عمليات التحقّق الأساسية بعد المعالجة على البلد والموقع الجغرافي للطلب / الرد. من الأفضل مقارنة عناوين الشوارع الفعلية بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.

ملاحظة: إذا قرّرت استخدام Geocoding API، ننصحك بإجراء عمليات التحقّق من جودة البيانات بين الطلب الأوّلي واستجابة Geocoding API بانتظام.

المطابقة الجزئية والمطابقة الخاطئة

إذا كان العنوان مطابقًا جزئيًا، أي أنّ Geocoding API لم يتمكّن من تحديد العنوان بدقة، سيتضمّن الردّ ما يلي:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

الأهم من أنواع المواقع الجغرافية المذكورة أعلاه هو مراعاة الحالات التي يكون فيها partial_match = true في الردّ. يشير الرمز partial_match إلى أنّ Geocoding API لم يعرض تطابقًا تامًا مع الطلب الأصلي، على الرغم من أنّه تمكّن من مطابقة جزء من العنوان المطلوب.

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

على سبيل المثال، تعرض "21 Henr St, Bristol, UK" مطابقة جزئية لكل من Henry Street وHenrietta Street. يُرجى العِلم أنّه إذا تضمّن الطلب مكوّن عنوان مكتوبًا بشكل خاطئ، قد تقترح Geocoding API عنوانًا بديلاً. لن يتم تصنيف الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها تطابق جزئي.

العناوين الاصطناعية

قد تعرض Geocoding API مواقع جغرافية لعناوين "اصطناعية" غير متوفّرة كمواقع جغرافية دقيقة في قاعدة بيانات Google.

في مثل هذه السيناريوهات، غالبًا ما يحتوي عنصر الاستجابة على معرّف مكان طويل، والسمة التالية: geometry.location_type=APPROXIMATE.

في حال ظهور هذه المؤشرات في الردّ، يُرجى وضع علامة على العنوان المدخل باعتباره غير صالح ومحاولة إعادة التحقّق من صحته بطريقة أخرى.

ملاحظة: هذا مثال آخر يمكنك من خلاله الحصول على ملاحظات مباشرة باستخدام Address Validation API في حال عدم توفّر عنوان.

فهم استجابة Address Validation API

تتوفّر حاليًا مستندات رائعة حول كيفية فهم الردود من Address Validation API، لذلك لن نتناول المزيد من التفاصيل هنا.

• يمكنك الاطّلاع على نظرة عامة على عنصر الرد هنا.
• يمكنك الاطّلاع هنا على عرض توضيحي يوضّح المكوّنات المختلفة للردّ.
• في مستند التحقّق من صحة العنوان عند الدفع، يتوفّر وصف تفصيلي لكيفية التمييز بين العناوين الصحيحة وغير الصحيحة.

أفضل الممارسات

تحديد الموقع الجغرافي

عند إجراء طلبات إلى واجهتَي برمجة التطبيقات Address Validation أو Geocoding، من أفضل الممارسات محاولة حصر الموقع الجغرافي الذي سيتم البحث فيه عن هذا العنوان. تنفّذ واجهتا برمجة التطبيقات ذلك بطريقتين مختلفتين:

• Geocoding API - Region Biasing

  إذا كنت تعرف أنّ الرموز الجغرافية ستكون ضمن بلد معيّن، ستحصل على نتائج أفضل بكثير باستخدام تحديد المنطقة المفضّلة. على سبيل المثال، إذا كنت تستخدم الترميز الجغرافي في كندا، ننصحك بإضافة &region=ca إلى طلباتك لتحديد كندا كخيار مفضّل. يُرجى العِلم أنّ ميزة "تفضيل المنطقة" تفضّل النتائج ضمن تلك المنطقة فقط. سيظل بإمكانك الحصول على نتائج خارج المنطقة.

• Address Validation API - رمز المنطقة

  وبطريقة مماثلة، تقدّم واجهة Address Validation API نتائج أكثر دقة إذا تم تمرير رمز ISO2 في الطلب، وذلك باستخدام الحقل regionCode.

تخزين أرقام تعريف الأماكن

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

لضمان حصولك دائمًا على أحدث المعلومات، عليك إعادة تحميل معرّفات الأماكن كل 12 شهرًا باستخدام طلب تفاصيل المكان مع المَعلمة place_id.

ملاحظة: يُرجى الحرص أيضًا على مراجعة دليل أفضل الممارسات الخاص بخدمة الترميز الجغرافي.

الخاتمة

يوضّح هذا المستند الاختلافات الأساسية بين واجهتَي Address Validation API وGeocoding API. باختصار، ننصحك باستخدام Address Validation API في الحالات التالية:

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

الخطوات التالية

يمكنك تنزيل المستند التعريفي حول تحسين عمليات الدفع والتوصيل والعمليات باستخدام العناوين الموثوقة ومشاهدة ندوة تحسين عمليات الدفع والتوصيل والعمليات باستخدام ميزة "التحقّق من صحة العنوان" .

محتوى إضافي للقراءة:

• خدمة "التحقّق من صحة العنوان" عند الدفع في مواقع التجارة الإلكترونية
• مستندات Place Autocomplete
• مستندات Address Validation API
• إعداد التقارير في "منصة خرائط Google"

المساهمون

تتولّى Google صيانة هذه المقالة. كتب المساهمون التاليون هذا المحتوى في الأصل.

المؤلفون الرئيسيون:

هنريك فالف | مهندس حلول

توما أنغلاريه | مهندس حلول

سارثاك جانجولي | مهندس حلول