قبول العنوان - أمثلة

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

ملاحظة: الأمثلة الواردة هنا توضيحية، ولكنّها لا تغطي جميع السيناريوهات.

مثال شائع: قبول

يوضّح هذا السيناريو عنوانًا يقبله نظامك أدخله أحد العملاء.

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

بيان لعنوان مقبول

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

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

بالإضافة إلى ذلك، يشير الرد إلى ما يلي:

• يظلّ "hasUnconfirmedComponents" false
• يظلّ "hasInferredComponents" false
• يظلّ "hasReplacedComponents" false
• يظلّ "hasSpellCorrectedComponents" false

وعند دمج هذه الإشارات معًا، فإنّها تشير إلى عنوان عالي الجودة.

الإجراء: قبول

أمثلة على الحالات الحدية: قبول

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

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

يوضّح هذا المثال إدخال عنوان إيطالي مع جميع مكوّنات العنوان الحالية، بالإضافة إلى عدم وجود مكوّنات مستنتَجة أو مستبدَلة. ومع ذلك، validationGranularity هو ROUTE.

العنوان الذي تم إدخاله	المنطقة
Via Fonte Grugnale, 14 unit 2, 66054 Vasto CH, Italia	إيطاليا

قرار بشأن رقم شارع غير مؤكّد

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "ROUTE",
  "geocodeGranularity": "ROUTE",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
}

يكشف التحقيق الإضافي في مكوّنات العنوان أنّ رقم الشارع هو UNCONFIRMED_BUT_PLAUSIBLE.

{
   "text": "14",
   "componentType": "street_number",
   "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

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

رقم شارع غير مؤكَّد في الولايات المتحدة

يوضّح هذا المثال إدخال عنوان في الولايات المتحدة مع توفّر جميع مكوّنات العنوان، بدون مكوّنات مستنتَجة أو مستبدَلة. ومع ذلك، validationGranularity هو PREMISE_PROXIMITY.

العنوان الذي تم إدخاله	المنطقة
975 Carson Dr, Sunnyvale, CA 94086	الولايات المتحدة

بيانات USPS لرقم شارع غير مؤكّد

{
   "firstAddressLine": "975 CARSON DR",
   "cityStateZipAddressLine": "SUNNYVALE CA 94086",
   "city": "SUNNYVALE",
   "state": "CA",
   "zipCode": "94086"
   "dpvConfirmation": "N",
   "dpvFootnote": "AAM3",
   "carrierRoute": "C031",
   "carrierRouteIndicator": "D",
   "postOfficeCity": "SUNNYVALE",
   "postOfficeState": "CA",
   "fipsCountyCode": "085",
   "county": "SANTA CLARA",
}

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

بيانات USPS غير مكتملة لعنوان مؤكّد

يوضّح هذا المثال إدخال عنوان في الولايات المتحدة مع تأكيد جميع مكوّنات العنوان، بدون مكوّنات مستنتَجة أو مستبدَلة، وvalidationGranularity بقيمة PREMISE. ومع ذلك، لم تتم تعبئة uspsData بالكامل، ولا يحتوي على قيمة dpvConfirmation.

العنوان الذي تم إدخاله	المنطقة
‎155 Via Condado Way, Palm Beach Gardens, FL 33418-1703	الولايات المتحدة

النتيجة لعنوان مؤكّد يتضمّن بيانات غير مكتملة من خدمة USPS

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

بيانات USPS لعنوان مؤكّد يتضمّن بيانات USPS غير مكتملة

{
  "standardizedAddress": {
    "firstAddressLine": "155 VIA CONDADO WAY",
    "cityStateZipAddressLine": "PALM BEACH GARDENS",
    "city": "PALM BEACH GARDENS",
    "state": "FL",
    "zipCode": "33418"
  },
  "carrierRoute": "H018",
  "postOfficeCity": "PALM BEACH GARDENS",
  "postOfficeState": "FL"
}

الإجراء: قبول. على الرغم من أنّ العنوان لم يتم تأكيده من خلال نظام DPV من قِبل خدمة البريد في الولايات المتحدة (USPS)، فإنّ validationGranularity من PREMISE يعطي إشارة قوية على أنّ هذا العنوان صالح. ومع ذلك، لزيادة مستوى الثقة، يمكنك أن تطلب من العميل تأكيد العنوان. لمزيد من التفاصيل، يُرجى الاطّلاع على إرشادات التنفيذ في قسم إنشاء منطق التحقّق.

ملاحظة: تتلقّى الخدمة بيانات USPS المعدَّلة بشكل دوري، لذا قد لا يعرض هذا المثال بيانات USPS غير المكتملة. هذا المثال توضيحي وليس تمثيلاً دقيقًا لردّ من واجهة برمجة التطبيقات لهذا العنوان.