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

الهدف

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

Address Checkation API هي عرض من "منصة خرائط Google" يساعد العملاء في التحقّق مما إذا كان العنوان دقيقًا أم لا.

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

يمكنك الاطّلاع هنا على نظرة عامة شاملة على الاختلافات بين "التحقق من صحة العناوين" وGeocoding API.

متى يجب اختيار "التحقق من صحة العنوان" مقابل Geocoding API

Address-Validation-vs-Geocoding

ملاحظات حول الرسم البياني التدفقي أعلاه:

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

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

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

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

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

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

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

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

1 Fake St, Mountain View, CA 94043, USA

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

alt_text

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

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

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

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

يمكن لكل من واجهة برمجة التطبيقات Address Profileation وGeocoding API تصحيح هذه الأخطاء وتحقيق نتيجة 76 Buckingham Palace Road, London, SW1W 9TQ. ومع ذلك، يمكن أن توفر واجهة برمجة تطبيقات التحقق من صحة العنوان مزيدًا من المعلومات حول هذه العملية.

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

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

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

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

Bollschestrase 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

هذا العنوان صحيح باستثناء رقم الوحدة (شارع 123)، الذي لا وجود له داخل المبنى.

يمكن لواجهة برمجة تطبيقات التحقق من صحة العنوان التحقُّق من صحة العنوان في 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%. لهذا السبب نحتاج إلى واجهة برمجة تطبيقات التحقق من صحة العنوان.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الخلاصة

يصف هذا المستند الاختلافات الأساسية بين واجهتَي برمجة تطبيقات "التحقّق من صحة العنوان" و"واجهات برمجة تطبيقات الترميز الجغرافي". باختصار، يمكنك استخدام واجهة برمجة تطبيقات التحقق من صحة العناوين في الحالات التالية:

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

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

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

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

المساهمون

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

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

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

توماس Anglaret | مهندس حلول

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