آشنایی با پاسخ اعتبارسنجی نشانی پایه

پاسخ Address Validation API حاوی این ویژگی‌های سطح بالا است:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

مشخصه verdict

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

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

رأی را در راهنمای مرجع ببینید.

دقت نشانی

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

خصوصیت verdict این سیگنال‌های دانه‌بندی را برمی‌گرداند:

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

کامل بودن نشانی

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

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

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

addressComplete را در زیر رأی و نشانی در راهنمای مرجع ببینید.

کیفیت نشانی

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

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

کنش بعدی احتمالی

فیلد حکم possibleNextAction خلاصه‌ای تفسیری از پاسخ میانای برنامه‌سازی کاربردی ارائه می‌دهد که هدف آن کمک به تعیین اقدام بعدی احتمالی است. این فیلد از فیلدهای دیگر در پاسخ میانای برنامه‌سازی کاربردی مشتق شده است و نباید به‌عنوان تضمینی برای دقت یا قابلیت تحویل نشانی درنظر گرفته شود.

مشخصه‌های address و addressComponent

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

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

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

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

مشخصه geocode

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

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

مشخصه metadata

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

پوشش Address Validation API و مرجع Address metadata را ببینید.

مشخصه uspsData

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

مدیریت نشانی‌های ایالات متحده و مرجع USPSData را ببینید.