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

الهدف

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

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

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

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

التجربة الآن: انتقِل إلى "وحدة تحكُّم Google Cloud" وفعِّل واجهة برمجة تطبيقات التحقُّق من صحة العنوان وواجهة برمجة التطبيقات للأماكن.

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

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

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

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

يمكنك اختيار استخدام واجهة برمجة تطبيقات التحقق من صحة العناوين عبر واجهة برمجة التطبيقات Geocoding API في الحالات التالية:

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

يمكنك اختيار استخدام ميزة "ترميز الموقع الجغرافي" بدلاً من 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 في ماونتن فيو بولاية كاليفورنيا، وتظهر هذه البيانات في تفاصيل مستوى المكوّن المعروض:

{
  "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 API تصحيح هذه الأخطاء وتحقيق النتيجة 76 Buckingham Palace Road, London, SW1W 9TQ. ومع ذلك، يمكن أن توفر واجهة برمجة تطبيقات التحقق من صحة العنوان مزيدًا من المعلومات حول هذه العملية.

ألقِ نظرة على أحد مكوّنات العنوان الذي تم إملائه بشكلٍ خاطئ عند الإدخال:

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

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

مثال على البيانات المفقودة وخطأ الإملاء

Bollschestraße 86, 12587, DE

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

يمكن لواجهة برمجة تطبيقات التحقق من صحة العناوين معالجة هذَين الخطأين وعرض رمز جغرافي لمستوى 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. لذلك، يعرض 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 إلى أنّ النتيجة المعروضة ليست أيًا مما سبق.

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

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

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

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

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

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

فهم استجابة واجهة برمجة التطبيقات للتحقق من صحة العناوين

هناك مستندات رائعة حاليًا حول كيفية فهم الردود من واجهة برمجة تطبيقات التحقق من صحة العنوان، لذلك لن ندخل في مزيد من التفاصيل هنا.

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

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

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

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

• Geocoding API - انحياز المنطقة

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

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

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

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

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

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

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

الخاتمة

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

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

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

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

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

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

المساهمون

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

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

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

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

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