تأیید آدرس - نمونه ها

این سند تعدادی از سناریوهای دنیای واقعی را شرح می‌دهد که در آن‌ها API اعتبارسنجی آدرس، سیگنال‌های پاسخی را برای آدرس‌هایی ارائه می‌دهد که ممکن است رفتار تأیید را از سیستم شما تضمین کنند. برای آشنایی با زمینه، به مثال‌های گردش کار در بخش «منطق اعتبارسنجی خود را بسازید» مراجعه کنید.

مثال‌های رایج: تأیید

مثال زیر، مورد مناطق شهری با نام‌های خیابانی مشابه را نشان می‌دهد. فرض کنید کاربری قصد دارد آدرس ساختمان D گوگل در کرکلند، واشنگتن، ایالات متحده را وارد کند. با این حال، به جای کرکلند به عنوان شهر، او سهواً سیاتل را وارد می‌کند.

آدرس وارد شده منطقه
ساختمان D، خیابان هفتم جنوبی، پلاک ۴۵۱، سیاتل، واشنگتن ۹۸۰۳۳ ما

حکم برای داده‌های جایگزین شده

مثال زیر بر سیگنال‌های مهم حاصل از پاسخ تأکید می‌کند.

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true,
  "possibleNextAction": "CONFIRM"
}

تابع possibleNextAction یک نشانه اولیه ارائه می‌دهد که ممکن است ارزش تأیید آدرس با مشتری شما را داشته باشد. سیگنال‌های دیگر در این حکم، جزئیات بیشتری از آنچه ممکن است در آدرس اشتباه باشد، ارائه می‌دهند. 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"
    ]

در این مورد، API اعتبارسنجی آدرس، تقریباً آدرس ارائه شده در سیاتل را پیدا کرد و کد پستی، یک جزء سطح بالاتر، را برای حل و فصل به آدرس سیاتل جایگزین کرد. این می‌تواند یک جایگزین معتبر باشد، اما با توجه به اینکه اجزا تأیید نشده بودند، منطقی است که اطمینان حاصل شود که کاربر قصد دارد آدرس سیاتل را وارد کند و نه چیز دیگری، مانند کرکلند.

مثال‌های موردی: تأیید

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

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

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

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

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

آدرس وارد شده منطقه
خیابان آلن، پلاک ۱۴۰۲، ماساچوست، کد پستی ۰۱۱۱۸ ما

حکم برای شهر گمشده 

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM"
}

در شرایطی که API اعتبارسنجی آدرس، اجزای سطح بالاتری را برای تولید یک آدرس قابل تحویل استنباط می‌کند، می‌توانید سطح اطمینان بالاتری از صحت داده‌های سیستم داشته باشید. دلیل این امر آن است که اجزای استنباط‌شده که نشان‌دهنده یک منطقه جغرافیایی وسیع هستند، با اجزای آدرس تأیید شده که جزئیات بیشتری دارند، راحت‌تر مطابقت دارند. حتی در کشورهایی که نام شهرها تکرار می‌شود، مانند اسپرینگفیلد در ایالات متحده، سایر اجزای ترکیب‌شده با آن می‌توانند یک آدرس منحصر به فرد ارائه دهند.

با استفاده از مثال بالا، اسکن تمام اجزای آدرس نشان می‌دهد که هر جزء تأیید شده است، به این معنی که با داده‌های ذخیره شده توسط API اعتبارسنجی آدرس مطابقت دارد و این سرویس همچنین دو جزء سطح بالاتر را استنباط می‌کند.

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

مؤلفه آدرس غیرمنتظره تأیید نشده است

این سناریو اهمیت بررسی عدم تأیید مؤلفه‌ها را نشان می‌دهد. اگر یک مؤلفه آدرس غیرمنتظره باشد، API اعتبارسنجی آدرس آن را از خروجی حذف می‌کند. در این موارد، بسته به سطح ریسک و سطح اطمینان خود، می‌توانید آدرس را بپذیرید یا آن را دوباره با مشتری تأیید کنید.

برای مثال، یک آدرس ممکن است از منطقه‌ای باشد که مشتریان اغلب اطلاعات بی‌ضرری را که توسط اداره پست نادیده گرفته می‌شود، وارد می‌کنند، در این صورت شما آدرس را می‌پذیرید. با این حال، در برخی موارد، یک جزء تأیید نشده ممکن است چیزی نباشد که مشتری می‌خواهد.

آدرس وارد شده منطقه
خیابان چری‌داون، پلاک ۵۹، چینگفورد، لندن، E4 8DT بریتانیا

حکم مربوط به مؤلفه آدرس غیرمنتظره تأیید نشده است 

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "unconfirmedComponents": true,
  "possibleNextAction": "ACCEPT"
}

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

"formattedAddress": "59 Cherrydown Avenue, London E4 8DT, UK",

اسکن اجزای تأیید نشده نشان می‌دهد که API، چینگفورد را از آدرس برگشتی حذف کرده است:

{
  "componentName": {
    "text": "Chingford",
    "languageCode": "en"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

مؤلفه آدرس غیرمنتظره‌ای که تأیید شده است

این مثال، گنجاندن یک شهرستان بریتانیا در آدرس ارائه شده را نشان می‌دهد که یک رویه رایج است. با این حال، این یک الزام از سوی اداره پست بریتانیا نیست و اساساً نادیده گرفته می‌شود. به postoffice.co.uk و نحوه آدرس‌دهی به نامه‌های بریتانیا و بین‌المللی مراجعه کنید.

در نتیجه، وقتی مشتری آدرس یک شهرستان در بریتانیا را ارائه می‌دهد، سرویس این را به عنوان ورودی غیرمنتظره ارزیابی می‌کند.

آدرس وارد شده منطقه
خیابان دانالی ۳۳، چلتنهام، گلاسترشر، GL50 4AP بریتانیا

حکم مربوط به مؤلفه آدرس غیرمنتظره که IS تأیید کرد 

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE",
   "possibleNextAction": "ACCEPT"
}

در اینجا، address_complete به false ارزیابی می‌شود و تجزیه و تحلیل مؤلفه آدرس، یک پرچم غیرمنتظره را نشان می‌دهد.

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

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