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

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

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

توضّح الأمثلة التالية أنواع الحالات القصوى التالية:

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

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

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

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

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

يوضّح هذا المثال تضمين مقاطعة في المملكة المتحدة في العنوان المقدَّم، وهو إجراء شائع. ومع ذلك، لا تطلب هيئة البريد في المملكة المتحدة ذلك، ويتم تجاهله بشكلٍ أساسي. راجِع postoffice.co.uk ومقالة How to address UK and international mail.

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

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