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

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

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

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

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

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

Missing subpremise

يصف هذا السيناريو عنوانًا لا يتضمّن سوى معلومات فرعية، مثل رقم الشقة أو القسم. بخلاف ذلك، يمكن لواجهة برمجة التطبيقات 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,
  "possibleNextAction": "CONFIRM_ADD_SUBPREMISES"
}

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

"missingComponentTypes": [
        "subpremise"
      ]

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

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