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

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

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

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

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

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

نتيجة عدم توفّر المدينة والرمز البريدي

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

{
  "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، مع بعض البيانات المهمة التي تم حذفها، مثل الموقع الجغرافي والرمز البريدي.

يجب إدخال رقم الشارع

يعرض هذا المثال رقم شارع غير متوفّر.

قرار بشأن رقم الشارع غير المتوفّر

{
    "inputGranularity": "PREMISE_PROXIMITY",
    "validationGranularity": "ROUTE",
    "geocodeGranularity": "ROUTE"
}

القيمة validationGranularity هي ROUTE، ما يشير إلى تطابق مع الشارع، ولكن لا تتوفّر معلومات كافية للوصول إلى المكان. بالإضافة إلى ذلك، فإنّ السمة addressComplete غير متوفّرة في الحكم، وبالتالي فإنّها false. يُظهر طلب بحث إضافي عن العنصر address نوع مكوّن مفقود:

"missingComponentTypes": [
        "street_number"
      ]

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

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

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

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

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

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

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

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

حكم بشأن عدم توفّر مكان فرعي

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

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "hasInferredComponents": true

}

يكشف استعلام address عمّا يلي:

"missingComponentTypes": [
        "subpremise"
      ]

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