تصحيح العنوان - أمثلة

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

ملاحظة: الأمثلة الواردة هنا توضيحية، ولكنها ليست شاملة.

الأمثلة الشائعة: إصلاح

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

عدم توفّر المدينة والرمز البريدي

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

العنوان الذي أدخلته	المنطقة
21 45 40th street	الولايات المتحدة الأمريكية

نتيجة عدم توفّر المدينة والرمز البريدي

يُبرز المثال أدناه الإشارات المهمة من الاستجابة.

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

تشير هذه الإشارات إلى عنوان لا يمكن تسليمه، لذا يمكنك الاستعلام عن addressComponents لمعرفة المزيد من المعلومات:

{
  "componentName": {
    "text": "21",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "45 40th street",
    "languageCode": "en"
  },
  "componentType": "route",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "United States",
    "languageCode": "en"
  },
  "componentType": "country",
  "confirmationLevel": "CONFIRMED"
}

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

الإجراء: بالنسبة إلى هذا العنوان، يُنصح بطلب العميل تقديم المعلومات غير المتوفّرة.

رقم الشارع غير متوفّر

يوضّح هذا المثال عدم توفّر رقم الشارع.

العنوان الذي أدخلته	المنطقة
Buckingham Palace Road, SW1W 9TQ London	المملكة المتحدة

نتيجة عدم توفّر رقم الشارع

{
    "inputGranularity": "PREMISE_PROXIMITY",
    "validationGranularity": "ROUTE",
    "geocodeGranularity": "ROUTE"
}

قيمة validationGranularity هي ROUTE، ما يشير إلى تطابق مع الشارع، ولكن لا تتوفّر معلومات كافية للوصول إلى المبنى. بالإضافة إلى ذلك، لا تتوفّر السمة addressComplete في البيان، وبالتالي فإنّه false. يكشف طلب بحث آخر عن address الكائن عن نوع مكوّن غير متوفّر:

"missingComponentTypes": [
        "street_number"
      ]

الإجراء: في هذه الحالة، الإجراء المقترَح هو مطالبة المستخدم بتقديم المعلومات غير المتوفّرة.

أمثلة على الحالات الحدّية: الإصلاح

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

لم يتم تأكيد رقم الشارع.

في هذا السيناريو، لا يمكن لواجهة برمجة التطبيقات Address Validation API تأكيد رقم الشارع الذي تم تقديمه، إلا أنّها تشير إلى أنّ العنوان كامل.

العنوان الذي أدخلته	المنطقة
84 Buckingham Palace Road, SW1W 9TQ, London	المملكة المتحدة

نتيجة رقم الشارع غير المؤكَّد

يُبرز المثال أدناه الإشارات المهمة.

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete" : true,
  "hasUnconfirmedComponents": true
}

من الجدير بالاهتمام التحقيق في الجمع بين دقة التحقّق فقط لتحديد القيمة التقريبة على مستوى الفرضيات، بالإضافة إلى المكوّنات غير المؤكَّدة. يعرض طلب بحث عن الموقع الإلكتروني addressComponents الcomponentType غير المؤكَّد التالي:

{
  "componentName": {
    "text": "84",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

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

الإجراء: يمكنك قبول الإدخال بالطريقة التي تم إدخالها بها أو التأكيد مع العميل لمعرفة ما إذا كان رقم الشارع الذي تم إدخاله غير مقصود أم لا. تعتمد استجابتك على مستوى المخاطر المرتبط بتسليمك. اطّلِع على إرشادات التنفيذ في قسم إنشاء منطق التحقّق.

عدم توفّر بيانات عن الموقع الفرعي

يصف هذا السيناريو عنوانًا لا يتضمّن سوى موقع فرعي، مثل رقم شقة أو قسم. بخلاف ذلك، يمكن لواجهة برمجة التطبيقات Address Validation API التحقّق من صحة العنوان بالكامل. وكما هي الحال عندما يكون أي مكوّن عنوان غير متوفّر، تكون قيمة addressComplete هي false وبالتالي لا تظهر عند الفحص اليدوي للقرار.

ملاحظة: في بعض البلدان، لا يمكن لواجهة برمجة التطبيقات Address Validation API رصد عدم توفّر SUB_PREMISE، في حين أنّ عدم توفّر SUB_PREMISE في الولايات المتحدة يشير إلى أنّ العنوان غير قابل للتسليم.

لتوضيح ذلك، افترض أن العميل أدخل عنوانًا صالحًا لمكتب تقييم مدينة سان فرانسيسكو، لكنه فقد رقم الغرفة من الإدخال.

تم إدخال العنوان	المنطقة
1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102	الولايات المتحدة الأمريكية

نتيجة عدم توفّر العنوان الفرعي

في هذا المثال، لا يعرض البيان السمة addressComplete، وبالتالي هو false. ولهذا السبب، يعني ذلك أنّ هناك عنصر عنوان واحدًا على الأقل غير متوقّع أو لم يتم حلّه أو غير متوفّر.

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "hasInferredComponents": true

}

يكشف طلب address عن ما يلي:

"missingComponentTypes": [
        "subpremise"
      ]

بعد إجراء المزيد من الاستفسارات، توفّر بيانات USPS رمز dpvConfirmation‏ D، ما يشير أيضًا إلى عدم توفّر موقع فرعي.

الإجراء: بالنسبة إلى هذا العنوان، يُنصح بطلب العميل تقديم المعلومات غير المتوفّرة.