التحقّق من صحة العنوان مقابل الترميز الجغرافي

الهدف

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

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

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

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

تجربة الآن: انتقِل إلى Google Cloud Console وفعِّل Address Validation API وPlaces API.

متى يجب اختيار Address Validation API بدلاً من Geocoding API؟

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

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

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

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

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

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

• هدفك الأساسي هو استرداد موقع عنوان معيّن، وقد لا تكون دقة العناوين الفردية مهمة.
  • على سبيل المثال، قد تريد إنشاء خريطة حرارية من مجموعة بيانات كبيرة.
• تحتاج إلى تفاصيل الوجهة المحلية جدًا، مثل مداخل المباني أو مخططاتها أو نقاط التنقّل للاستلام والتوصيل (المتوفّرة باستخدام طريقة SearchDestinations في Geocoding API v4).
• تحتاج إلى حلّ عالمي، ولا يتوفّر 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 API وGeocoding API تصحيح هذه الأخطاء وتحقيق النتيجة 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"

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

لا يمكن لـ Geocoding API تقديم هذه المعلومات.

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

نظرة عامة

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

تتمثل طريقة عمل Geocoding API في حلّ مكوّنات العنوان في تسلسل هرمي.

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

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

ChIJwRKzf8ixD4gRHiXqucwr_HQ

تحتوي Geocode API على المعلومات التالية في الردّ:

        "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 for checkout، يتوفّر وصف تفصيلي لكيفية التمييز بين العناوين الجيدة والسيئة.

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

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

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

• ‫Geocoding API - التحيز على مستوى المنطقة

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

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

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

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

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

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

ملاحظة: يُرجى أيضًا مراجعة دليل أفضل الممارسات لـ Geocoding API.

الخاتمة

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

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

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

يمكنك تنزيل المستند التقني Improve checkout, delivery, and operations with reliable addresses والاطّلاع على Improving checkout, delivery, and operations with Address Validation Webinar.

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

• Address Validation for Ecommerce Checkout
• مستندات الإكمال التلقائي للأماكن
• مستندات Address Validation API
• إعداد التقارير في "منصة خرائط Google"

المساهمون

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

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

Henrik Valve | مهندس حلول

Thomas Anglaret | مهندس حلول

Sarthak Ganguly | مهندس حلول