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

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

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

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

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

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

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

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

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

يؤكّد المثال أدناه على الإشارات المهمة من الردّ.

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

يوفّر possibleNextAction مؤشرًا أوليًا على أنّ العنوان قد لا يكون قابلاً للتسليم. تتيح المكوّنات الأخرى المميّزة أيضًا هذه الإمكانية، لذا يمكنك الاستعلام من 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",
    "possibleNextAction": "FIX"
}

مرة أخرى، يقدّم possibleNextAction مؤشرًا أوليًا على أنّ العنوان قد لا يكون قابلاً للتسليم. بالإضافة إلى ذلك، فإنّ validationGranularity هو ROUTE، ما يشير إلى تطابق مع الشارع، ولكن لا توجد معلومات كافية للوصول إلى المبنى. بالإضافة إلى ذلك، لا تتوفّر السمة addressComplete في القرار، وبالتالي فهي false. يكشف الاستعلام الإضافي عن الكائن address عن نوع مكوّن مفقود:

"missingComponentTypes": [
        "street_number"
      ]

الإجراء: بالنسبة إلى هذا العنوان، يمكنك أن تطلب من المستخدم تقديم المعلومات الناقصة.

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

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

رقم الشارع غير مؤكَّد

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

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

Verdict for unconfirmed street number

يؤكّد المثال أدناه على الإشارات المهمة.

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

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

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

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

Verdict for missing subpremise

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

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM_ADD_SUBPREMISES"
}

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

"missingComponentTypes": [
        "subpremise"
      ]

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

الإجراء: بالنسبة إلى هذا العنوان، يمكنك أن تطلب من المستخدم إدخال المعلومات الناقصة.