تأكيد العنوان - أمثلة

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

ملاحظة: الأمثلة الواردة هنا توضيحية، ولكنّها لا تغطي جميع السيناريوهات.

أمثلة شائعة: تأكيد

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

تم إدخال العنوان	المنطقة
Building D, 451 7th Avenue South, Seattle, WA 98033	الولايات المتحدة

نتيجة البيانات المستبدَلة

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

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true,
  "possibleNextAction": "CONFIRM"
}

تقدّم possibleNextAction مؤشرًا أوليًا على أنّه قد يكون من المفيد تأكيد العنوان مع العميل. تقدّم الإشارات الأخرى في الحكم تفاصيل أكثر حول المشاكل المحتملة في العنوان. يشير الرمز PREMISE_PROXIMITY إلى تقريب عنوان على مستوى المبنى، ولكنّه ليس مفصّلاً مثل SUB_PREMISE، وهو مستوى التفصيل المقدَّم في الإدخال. يحتوي الردّ أيضًا على مكوّنات غير مؤكَّدة ومستبدَلة.

يكشف طلب البحث عن مكوّنات العنوان عن المشاكل التالية:

{
  "componentName": {
    "text": "451",
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
  "componentName": {
    "text": "98104",
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "replaced": true
}
...
{
  "componentName": {
    "text": "Building D",
    "language_code": "en"
  },
  "componentType": "subpremise",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......

    "unconfirmedComponentTypes": [
      "street_number",
      "subpremise"
    ]

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

ملاحظة: تحقَّق من العنوان الصحيح في العرض التوضيحي باستخدام 451 7th Avenue South, Kirkland, WA 98033 للاطّلاع على الردّ الخاص بالعنوان المقصود أصلاً.

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

أمثلة على الحالات القصوى: تأكيد

توضّح الأمثلة التالية أنواع حالات الاستخدام الحدّية:

• الاستنتاجات البسيطة التي تم تأكيدها تستنتج واجهة برمجة التطبيقات Address Validation API البلد أو الرمز البريدي أو الولاية، ولكن يتم تقديم كل المعلومات الأخرى وتأكيدها. يؤدي الجمع بين مستوى التفاصيل ومستوى التأكيد إلى استنتاج بسيط لا يتطلّب بالضرورة إجراء تأكيد.
• لم يتم تأكيد عنصر العنوان غير المتوقّع. تزيد مكوّنات العنوان غير المؤكَّدة من مستوى خطورة العنوان. قد يتطلّب ذلك تأكيدًا.
• عنصر عنوان غير متوقّع تم تأكيده هذا المكوّن غير مطلوب بشكل صارم لعنوان صالح، وتزيله واجهة برمجة التطبيقات Address Validation API من الناتج. لا تتطلّب مشاكل التنسيق عادةً تأكيدًا.

الاستنتاجات البسيطة التي تم تأكيدها

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

• المدينة
• ولاية
• الرمز البريدي
• البلد

على سبيل المثال، يقدّم العميل عنوان شارع صالحًا لمطعم McDonald's في سبرينغفيلد، ماساتشوستس، لكنّه ينسى إدخال المدينة ويقدّم رمزًا بريديًا بدون الرقم الإضافي المكوّن من 4 أرقام.

تم إدخال العنوان	المنطقة
1402 Allen St, MA 01118	الولايات المتحدة

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

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM"
}

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

باستخدام المثال أعلاه، يوضّح الفحص لجميع مكوّنات العنوان أنّه تم تأكيد كل مكوّن، ما يعني أنّه يتطابق مع البيانات المخزّنة في Address Validation API، وأنّ الخدمة تستنتج أيضًا مكوّنَين من المستوى الأعلى.

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

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

لم يتم تأكيد مكوّن العنوان غير المتوقّع

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

على سبيل المثال، قد يكون العنوان من منطقة يدخل فيها العملاء غالبًا معلومات غير ضارة تتجاهلها هيئة البريد، وفي هذه الحالة، عليك قبول العنوان. ومع ذلك، في بعض الحالات، قد لا يكون المكوّن غير المؤكَّد هو ما يريده العميل.

تم إدخال العنوان	المنطقة
59 Cherrydown Avenue, Chingford, London E4 8DT	المملكة المتحدة

لم يتم تأكيد نتيجة مكوّن العنوان غير المتوقّع

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "unconfirmedComponents": true,
  "possibleNextAction": "ACCEPT"
}

بالإضافة إلى نتيجة تتضمّن مكوّنات لم يتم تأكيدها، تعرض واجهة Address Validation API العنوان المنسّق التالي:

"formattedAddress": "59 Cherrydown Avenue, London E4 8DT, UK",

يُظهر فحص المكوّنات غير المؤكَّدة أنّ واجهة برمجة التطبيقات أزالت Chingford من العنوان الذي تم عرضه:

{
  "componentName": {
    "text": "Chingford",
    "languageCode": "en"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

الإجراء: في هذه الحالة، قد تكون المنطقة الفرعية، التي يمكن أن تشير إلى حي سكني أو حي، صحيحة ولكنها لا تزال غير معترف بها من قِبل هيئة البريد. ومع ذلك، بما أنّ واجهة برمجة التطبيقات Address Validation API **لا** تؤكّد هذه المعلومات، ننصحك بالتأكّد منها مع العميل. في هذه المرحلة، يمكنك إما تجاهل الإزالة أو تأكيدها.

مكوّن عنوان غير متوقّع تم تأكيده

يوضّح هذا المثال تضمين مقاطعة في المملكة المتحدة في العنوان المقدَّم، وهو أمر شائع. ومع ذلك، لا يشترط مكتب البريد في المملكة المتحدة ذلك، ويتم تجاهله بشكل أساسي. يُرجى الاطّلاع على postoffice.co.uk و كيفية عنونة الرسائل البريدية في المملكة المتحدة وعلى المستوى الدولي.

نتيجةً لذلك، عندما يقدّم العميل مقاطعة في عنوان في المملكة المتحدة، تعتبر الخدمة أنّ هذا الإدخال غير متوقّع.

تم إدخال العنوان	المنطقة
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP	المملكة المتحدة

نتيجة الجزء غير المتوقّع من العنوان الذي تم تأكيده

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE",
   "possibleNextAction": "ACCEPT"
}

في هذه الحالة، يتم تقييم address_complete على أنّه خطأ، ويكشف تحليل مكوّن العنوان عن علامة غير متوقّعة.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

هذا المكوّن غير متوقّع وتم تأكيده، ما يعني ما يلي:

• تم تأكيد صحة البيانات يشير ذلك إلى أنّ المكوّن هو المقاطعة الصحيحة التي يتضمّنها العنوان.
• قيمة غير متوقّعة كمدخل تشير إلى عنصر غير مطلوب للتنسيق السليم للعنوان.

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

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