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

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

ملاحظة: الأمثلة الواردة هنا توضيحية، ولكنها ليست شاملة.

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

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

العنوان الذي أدخلته	المنطقة
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
}

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

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

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

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

العنوان الذي أدخلته	المنطقة
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 على أنّه خطأ، ويكشف تحليل المكوّن address عن علامة غير متوقّعة.

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

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

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

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

الإجراء: بالنسبة إلى هذا السيناريو، ننصحك بتجاهل هذه الإشارة وقبول العنوان.