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

الهدف

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

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

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

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

جرِّب الآن: انتقِل إلى وحدة تحكّم Google Cloud وفعِّل واجهة برمجة التطبيقات Address Validation API وPlaces 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 ذلك في التفاصيل التي يتم عرضها على مستوى المكوّن:

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

premises:

"business": true

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

"dpvConfirmation": "S"

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

لا تستطيع واجهة برمجة تطبيقات الترميز الجغرافي توفير هذه المعلومات.

فهم الردّ من 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، من أفضل الممارسات محاولة حصر الموقع الجغرافي الذي سيتم البحث فيه عن هذا العنوان. تنفذ واجهتا برمجة التطبيقات هذا الأمر بطريقتين مختلفتين:

• واجهة برمجة تطبيقات الترميز الجغرافي - التحيز الإقليمي

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

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

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

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

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

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

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

الخاتمة

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

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

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

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

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

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

المساهمون

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

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

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

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

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