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

API اعتبارسنجی آدرس، یک بدنه پاسخ به عنوان یک شیء JSON ارائه می‌دهد که شامل دو ویژگی سطح بالا است:

{
  "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 یک آدرس با کیفیت خوب را نشان می‌دهد که برای این درخواست خاص ۴ فیلد را برمی‌گرداند:

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

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

به حکم در راهنمای مرجع مراجعه کنید.

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

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

جزئیات آدرس

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

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

  • inputGranularity — سطح جزئیات گرفته شده از آدرس ارسال شده به API اعتبارسنجی آدرس را توصیف می‌کند. سطح جزئیات آدرس در درخواست، بر سطح جزئیات آدرس در پاسخ اعتبارسنجی تأثیر می‌گذارد. به عنوان مثال، آدرسی با inputGranularity زیر سطح PREMISE معمولاً منجر به validationGranularity تا سطح PREMISE نمی‌شود.
  • validationGranularity — سطح جزئی‌نگری که API اعتبارسنجی آدرس می‌تواند آدرس را به طور کامل تا آن اعتبارسنجی کند. در بیشتر موارد، سطح جزئی‌نگری PREMISE یا SUB_PREMISE نشان دهنده یک آدرس با کیفیت است که احتمالاً قابل تحویل است.
  • geocodeGranularity — سطح جزئیات geocode مرتبط با آدرس را توصیف می‌کند. برای مثال، رکوردهای گوگل ممکن است وجود شماره آپارتمان را نشان دهند، اما مکان دقیقی برای آن آپارتمان خاص در یک مجتمع آپارتمانی بزرگ را نشان ندهند. در این صورت، validationGranularity SUB_PREMISE است اما geocodeGranularity برابر با PREMISE` is .
به بخش «جزئیات» در راهنمای مرجع مراجعه کنید.

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

این حکم، ویژگی addressComplete را به عنوان سیگنالی برای یک آدرس با کیفیت بالا برمی‌گرداند، که به طور خاص به این معنی است که هیچ جزء گمشده، حل نشده یا غیرمنتظره‌ای ندارد:

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

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

به addressComplete در بخش «حکم» و «آدرس» در راهنمای مرجع مراجعه کنید.

کیفیت آدرس

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

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
به حکم در راهنمای مرجع مراجعه کنید.

ویژگی‌های address و addressComponent

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

Address در راهنمای مرجع مراجعه کنید.

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

به addressComponent در راهنمای مرجع مراجعه کنید.

ویژگی geocode

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

به Geocode در راهنمای مرجع مراجعه کنید.

ویژگی metadata

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

به پوشش API اعتبارسنجی آدرس و مرجع Address metadata مراجعه کنید.

ویژگی uspsData

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

به بخش «مدیریت آدرس‌های ایالات متحده» و مرجع مربوط به UspsData مراجعه کنید.