تأیید نشانی - مثال‌ها

این سند تعدادی از سناریوهای دنیای واقعی را شرح می‌دهد که در آن‌ها 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 تقریب نزدیکی به نشانی ارائه‌شده در سیاتل پیدا کرد و کد پستی را که مؤلفه سطح بالاتری است جایگزین کرد تا به نشانی سیاتل تبدیل شود. این می‌تواند جایگزین معتبری باشد، اما همراه با این واقعیت که مؤلفه‌ها تأیید نشده‌اند، منطقی است که مطمئن شویم کاربر قصد دارد نشانی سیاتل را وارد کند و نه چیز دیگری مانند کرکلند.

نکته: نشانی صحیح را در نسخه نمایشی بررسی کنید، بااستفاده از 451 7th Avenue South, Kirkland, WA 98033 پاسخ نشانی موردنظر اصلی را ببینید.

اقدام: ورودی نشانی را با مشتری تأیید کنید.

نمونه‌های موارد حاشیه‌ای: تأیید

مثال‌های زیر انواع موارد لبه‌ای را نشان می‌دهند:

• استنتاج‌های جزئی که تأیید شده‌اند. Address Validation API کشور، کد پستی، یا ایالت را استنباط می‌کند، اما همه موارد دیگر هم ارائه و هم تأیید شده است. ترکیب هر دو سطح جزئیات و تأیید باعث می‌شود که استنتاج جزئی لزوماً به کنش تأیید نیاز نداشته باشد.
• بخش غیرمنتظره نشانی تأیید نشد. بخش‌های تأییدنشده نشانی به سطح ریسک نشانی اضافه می‌کند. این ممکن است نیاز به تأیید داشته باشد.
• بخش غیرمنتظره‌ای از نشانی که تأیید شده است. این مؤلفه برای نشانی صحیح کاملاً ضروری نیست و Address Validation API آن را از برونداد برمی‌دارد. مشکلات قالب‌بندی معمولاً نیازی به تأیید ندارند.

استنتاج‌های جزئی که تأیید شده‌اند

وقتی با داده‌های تأییدشده در سطح جزئی‌تر ترکیب شود، اگر ورودی فقط یک مؤلفه از انواع زیر را نداشته باشد، API همچنان می‌تواند استنتاج درستی انجام دهد:

• شهر
• ایالت
• کد پستی
• کشور

برای مثال، مشتری نشانی خیابان معتبری برای رستوران مک‌دونالد در اسپرینگفیلد، ماساچوست ارائه می‌دهد، اما فراموش می‌کند شهر را وارد کند و کد پستی را بدون پسوند ۴ رقمی ارائه می‌دهد.

نشانی واردشده	منطقه
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",

اسکن برای قطعات تأییدنشده نشان می‌دهد که API la caritat 2 را از نشانی برگردانده‌شده برداشته است:

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

کنش: تأیید. در این مورد، زیرمنطقه که می‌تواند نشان‌دهنده منطقه مسکونی یا محله باشد، ممکن است درست باشد اما همچنان توسط اداره پست نادیده گرفته شود. بااین‌حال، ازآنجایی‌که این اطلاعات توسط Address Validation API تأیید **نشده** است، منطقی است که این موضوع را با مشتری تأیید کنید. در این مرحله، یا درخواست برداشتن را نادیده می‌گیرید یا آن را تأیید می‌کنید.

بخش غیرمنتظره نشانی که تأیید شده است

این مثال نشان می‌دهد که شهرستان بریتانیا در نشانی ارائه‌شده گنجانده شده است، که یک روش معمول است. بااین‌حال، این مورد از الزامات اداره پست پادشاهی متحد (UK) نیست و اساساً نادیده گرفته می‌شود. postoffice.co.uk و نحوه آدرس‌دهی نامه‌های بین‌المللی و پادشاهی متحد (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
}

این قطعه هم غیرمنتظره است و هم تأییدشده، که یعنی:

• به‌عنوان داده صحیح تأیید شد. این نشان می‌دهد که بخش، شهرستان درستی است که نشانی را دربرمی‌گیرد.
• غیرمنتظره به‌عنوان ورودی. نشان‌دهنده مؤلفه‌ای است که برای قالب‌بندی صحیح نشانی لازم نیست.

اگرچه گلاسترشر شهرستان صحیح برای نشانی واردشده است، اما خود نشانی به‌درستی قالب‌بندی نشده است. به‌یاد داشته باشید که Address Validation API اطلاعات را برای قالب‌بندی مناسب نیز ارزیابی می‌کند.

اقدام: برای این سناریو، اقدام توصیه‌شده این است که این سیگنال را نادیده بگیرید و نشانی را بپذیرید.