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

الهدف

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

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

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

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

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

حالات اختيار Address Validation مقابل 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 في الإصدار 4 من Geocoding API).
• أنت بحاجة إلى حلّ عالمي، ولا تتوفّر واجهة Address Validation API في جميع المناطق المستهدَفة.

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

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

1 Fake St, Mountain View, CA 94043, USA

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

لا يتوفّر Fake St في ماونتن فيو، كاليفورنيا، وتعكس واجهة 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، يمكن إجراء مطابقة على "California"، كما هو موضّح في لقطة الشاشة التالية من أداة الترميز الجغرافي:

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

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

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

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

يمكن لكلّ من Address Validation و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)، وتقديم بعض البيانات الوصفية حول الموقع الجغرافي، بما في ذلك أنّه موقع تجاري

premises:

"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 وشارع Henrietta. يُرجى العِلم أنّه إذا تضمّن الطلب مكوّن عنوان يحتوي على أخطاء إملائية، قد تقترح Geocoding API عنوانًا بديلاً. ولن يتم وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.

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

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

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

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

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

فهم ردّ من واجهة برمجة التطبيقات Address Validation API

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

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

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

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

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

• Geocoding API - Region Biasing

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

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

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

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

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

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

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

الخاتمة

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

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

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

يمكنك تنزيل المستند التعريفي تحسين عمليات الدفع والتسليم والعمليات باستخدام عناوين موثوقة والاطّلاع على البرنامج التعليمي على الويب تحسين عمليات الدفع والتسليم والعمليات باستخدام Address Validation .

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

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

المساهمون

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

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

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

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

سارثاك غانغولي، مهندس حلول