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

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

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

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

يوضّح هذا القسم أمثلة شائعة توفّر فيها واجهة برمجة التطبيقات 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، ما يشير أيضًا إلى عدم توفّر موقع فرعي.

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