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

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

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

عدم توفّر بيانات عن الموقع الفرعي

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

ملاحظة: في بعض البلدان، لا يمكن لواجهة برمجة التطبيقات Address Validation API رصد عدم توفّر SUB_PREMISE، في حين أنّ عدم توفّر 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، ما يشير أيضًا إلى عدم توفّر موقع فرعي.

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