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

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

يشير مستوى 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
}

في الحالات التي تستنتج فيها 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 من الناتج. في هذه الحالات، يمكنك إما قبول العنوان أو إعادة تأكيده مع العميل، وذلك حسب مستوى المخاطرة ومستوى الثقة.

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

العنوان الذي تم إدخاله	المنطقة
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry	فرنسا

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

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

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

"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",

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

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "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"
}

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

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

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

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

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

الإجراء: في هذه الحالة، الإجراء المقترَح هو تجاهل هذه الإشارة وقبول العنوان.