پاسخ اعتبارسنجی آدرس اولیه را درک کنید

Address Validation API یک بدنه پاسخ را به عنوان یک شی JSON ارائه می دهد که حاوی دو ویژگی سطح بالا است:

• result ، یک شی از نوع ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

این سند بر روی شی result تمرکز می کند. برای کسب اطلاعات در مورد responseID ، به مدیریت آدرس های به روز شده مراجعه کنید.

اموال verdict

ویژگی verdict نتایج اعتبار سنجی آدرس را خلاصه می کند و باید اولین خاصیتی باشد که هنگام ساخت منطق بررسی آدرس، ارزیابی می شود. این ویژگی بسته به کیفیت آدرس خروجی می تواند فیلدهای مختلفی را برگرداند. به عنوان مثال، شکل زیر ویژگی verdict یک آدرس با کیفیت خوب را نشان می دهد که 4 فیلد را برای این درخواست خاص برمی گرداند:

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

بخش‌های زیر تمام فیلدهای ویژگی verdict را خلاصه می‌کند.

اقدام بعدی احتمالی

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

جزئیات آدرس

دانه بندی آدرس به سطح جزئیات مورد استفاده در تعیین ویژگی یک آدرس یا ژئوکد اشاره دارد. ویژگی آدرس در پاسخ validationGranularity یک سیگنال کلیدی برای اینکه آیا یک آدرس قابل تحویل است یا خیر است.

ویژگی verdict این سیگنال های گرانولیتی را برمی گرداند:

• inputGranularity - سطح جزئیات گرفته شده از آدرس ارسال شده به Address Validation API را توصیف می کند. سطح جزئیات آدرس در درخواست بر سطح جزئیات آدرس در پاسخ اعتبارسنجی تأثیر می گذارد. به عنوان مثال، آدرسی با inputGranularity زیر PREMISE زیر سطح معمولاً منجر به validationGranularity به سطح PREMISE نمی شود.
• validationGranularity - سطح granularity که Address Validation API می تواند آدرس را به طور کامل تایید کند. در بیشتر موارد، سطح جزئیات PREMISE یا SUB_PREMISE نشان دهنده یک آدرس با کیفیت است که احتمالا قابل تحویل است.
• geocodeGranularity - سطح جزئیات ژئوکد مرتبط با آدرس را توصیف می کند. به عنوان مثال، سوابق Google ممکن است وجود یک شماره آپارتمان را نشان دهد، اما مکان دقیقی برای آن آپارتمان خاص در یک مجتمع آپارتمانی بزرگ نیست. در آن صورت، validationGranularity SUB_PREMISE است اما geocodeGranularity PREMISE` is .

کامل بودن آدرس

حکم، ویژگی addressComplete را به عنوان سیگنالی برای یک آدرس با کیفیت بالا برمی‌گرداند، به این معنی که هیچ مؤلفه گمشده، حل‌نشده یا غیرمنتظره‌ای ندارد:

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

هنگامی که آدرس دارای اجزای مفقود، حل نشده یا غیرمنتظره باشد، فیلد روی false تنظیم می شود.

کیفیت آدرس

تعدادی از فیلدهای ممکن مشکلات اجزای آدرس یا تنظیمات مربوط به آنها را نشان می دهد، مانند اجزای آدرس استنباط شده یا گمشده. به عنوان مثال، ویژگی verdict زیر یک آدرس با اجزای تایید نشده و یک قسمت از دست رفته addressComplete نشان می دهد:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

ویژگی های address و addressComponent

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

ویژگی addressComponent یک جزء فرعی از address است که فهرست دقیقی از عناصر یا اجزای آدرسی را که Address Validation API پردازش کرده است ارائه می دهد. API هر فیلد مؤلفه را با نام، نوع و سطح تأیید آن شناسایی می کند.

ویژگی geocode

ویژگی geocode مکان جغرافیایی کد شده مرتبط با آدرس ورودی را نشان می دهد. این ویژگی جزئیاتی را درباره خود مکان ارائه می دهد، مانند شناسه مکان آن.

خاصیت metadata

این ویژگی ممکن است برای هر آدرسی که توسط Address Validation API پردازش می‌شود پر نشود، اما نشان می‌دهد که آدرس از نوع مسکونی، تجاری یا صندوق پستی است.

ویژگی uspsData

این ویژگی اطلاعات مفیدی را برای آدرس های پستی ایالات متحده ارائه می دهد. با این حال، تضمین نمی شود که برای هر آدرسی که توسط سرویس تأیید شده است، به طور کامل پر شود. به همین دلیل، شما نباید به این ویژگی به عنوان تنها وسیله اعتبارسنجی آدرس ها اعتماد کنید، بلکه باید verdict و address نیز بررسی کنید.