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

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

ملاحظة: افتح النسخة التجريبية من Address Validation وحاوِل التحقّق من صحة العناوين النموذجية بنفسك.

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

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

العنوان الذي تم إدخاله	المنطقة
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 من الناتج. لا تتطلب مشاكل التنسيق عادةً تأكيدًا.

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

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

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

على سبيل المثال، يقدّم العميل عنوان شارع صالحًا لمطعم ماكدونالدز في سبرينغفيلد، ماساتشوستس، ولكنه ينسى إدخال المدينة ويقدّم رمزًا بريديًا بدون الامتداد المكوّن من 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
}

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

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

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

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