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

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

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

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

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

تم إدخال العنوان	المنطقة
المبنى (د)، 451 شارع 7 جنوب، سياتل، واشنطن 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 على عنوان مشابه لعنوان العميل الذي تم تقديمه في دبي، واستبدلت الرمز البريدي، وهو مكوّن من مستوى أعلى، لتحويله إلى عنوان دبي. قد يكون هذا بديلاً صالحًا، ولكن بالإضافة إلى حقيقة أنّه لم يتم تأكيد المكوّنات، من المنطقي التأكّد من أنّ المستخدم يريد إدخال عنوان في سياتل وليس عنوانًا آخر، مثل Kirkland.

ملاحظة: تحقّق من العنوان الصحيح في العرض التجريبي، باستخدام 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
}

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

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

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

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

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

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

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

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