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

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

ملاحظة: افتح النسخة التجريبية من 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	المملكة المتحدة

Verdict for unconfirmed street number

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

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

ملاحظة: في بعض البلدان، لا يمكن لواجهة Address Validation API رصد مبنى فرعي غير متوفّر، بينما في الولايات المتحدة، يشير عدم توفّر SUB_PREMISE إلى عنوان غير قابل للتسليم.

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

العنوان الذي أدخلته	المنطقة
‎1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102	الولايات المتحدة الأمريكية

Verdict for missing subpremise

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

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

}

يكشف طلب البحث عن address ما يلي:

"missingComponentTypes": [
        "subpremise"
      ]

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

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