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

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