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

الهدف

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

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

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

يمكنك الاطّلاع على نظرة عامة عالية المستوى على الاختلافات بين Address Validation و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، مثل تصنيف نوع المبنى على أنّه سكني أو تجاري.

يمكنك اختيار استخدام ميزة "ترميز الموقع الجغرافي" بدلاً من Address Validation API في الحالات التالية:

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

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

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

1 Fake St, Mountain View, CA 94043, USA

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

لا تقع شارع Fake في ماونتن فيو، كاليفورنيا، وتوضّح واجهة برمجة التطبيقات 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 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. لذلك، يعرض الرمز البريدي التالي Place_id:

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 إلى أنّ النتيجة المعروضة ليست أيًا مما سبق.

إذا كانت واجهة برمجة تطبيقات ترميز المواقع الجغرافية تعرض location_type من النوع ROOFTOP أو RANGE_INTERPOLATED، لا يعني ذلك بالضرورة أنّ العنوان متوفّر. وبالمثل، إذا كانت واجهة برمجة تطبيقات ترميز المواقع الجغرافية تعرض العلامة 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 API

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

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

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

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

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

المساهمون

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

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

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

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

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