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

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

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

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