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

هذا المنتج أو الميزة متوفّران في مرحلة المعاينة (قبل طرحه للجميع). قد يكون الدعم المقدَّم للمنتجات والميزات في مرحلة ما قبل الإصدار العلني محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات في مرحلة ما قبل الإصدار العلني متوافقة مع الإصدارات الأخرى من مرحلة ما قبل الإصدار العلني. تخضع "عروض مرحلة ما قبل الإطلاق" لالبنود الخاصة بخدمة "منصّة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مرحلة الإطلاق.

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

ملاحظة: يمكنك فتح العرض التوضيحي لميزة "التحقّق من العنوان" ومحاولة التحقّق من صحة أمثلة العناوين بنفسك.

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

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

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

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

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

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

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

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