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

يوضّح هذا المستند عددًا من السيناريوهات الواقعية التي تقدّم فيها واجهة 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 المفقود في الولايات المتحدة إلى أنّ العنوان غير صالح للتسليم.

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

تم إدخال العنوان	المنطقة
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، ما يشير أيضًا إلى عدم توفّر عنوان فرعي.

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