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

پاسخ 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 — سطح جزئیات گرفته شده از آدرس ارسال شده به Address Validation در Maps JavaScript API را توصیف می‌کند. سطح جزئیات آدرس در درخواست، بر سطح جزئیات آدرس در پاسخ اعتبارسنجی تأثیر می‌گذارد. به عنوان مثال، آدرسی با inputGranularity زیر سطح PREMISE معمولاً منجر به validationGranularity تا سطح PREMISE نمی‌شود.
  • validationGranularity - سطح دانه‌بندی که اعتبارسنجی آدرس در API جاوا اسکریپت Maps می‌تواند آدرس را به طور کامل تا آن اعتبارسنجی کند. در بیشتر موارد، سطح دانه‌بندی PREMISE یا SUB_PREMISE نشان دهنده یک آدرس با کیفیت است که احتمالاً قابل تحویل است.
  • geocodeGranularity — سطح جزئیات geocode مرتبط با آدرس را توصیف می‌کند. برای مثال، رکوردهای گوگل ممکن است وجود شماره آپارتمان را نشان دهند، اما مکان دقیقی برای آن آپارتمان خاص در یک مجتمع آپارتمانی بزرگ را نشان ندهند. در این صورت، validationGranularity برابر با SUB_PREMISE است اما geocodeGranularity PREMISE است.
به بخش «جزئیات» در راهنمای مرجع مراجعه کنید.

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

این حکم، ویژگی 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 خلاصه‌ای تفسیری از پاسخ API ارائه می‌دهد که برای کمک به تعیین اقدام بعدی احتمالی در نظر گرفته شده است. این فیلد از سایر فیلدهای پاسخ API گرفته شده است و نباید به عنوان تضمینی برای دقت یا قابلیت تحویل آدرس در نظر گرفته شود.

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

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

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

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

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

ویژگی geocode

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

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

ویژگی metadata

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

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

ویژگی uspsData

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

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