اعتبارسنجی نشانی درمقابل زمین‌کدیابی

هدف اصلی

اغلب نیاز دارید مکان جایی را اعتبارسنجی کنید. چند سرویس مختلف در «پلاتفرم Google Maps» وجود دارد که می‌تواند در این مورد استفاده به شما کمک کند. این سند به شما کمک می‌کند بین دو سرویس اصلی اعتبارسنجی مکان - Address Validation API و Geocoding API - انتخاب کنید.

Address Validation API یکی از محصولات «پلاتفرم Google Maps» است که به مشتریان کمک می‌کند درست بودن یا نبودن نشانی را اعتبارسنجی کنند.

«زمین‌کدگذاری» با Geocoding API فرایند تبدیل نشانی‌ها به مختصات جغرافیایی است که می‌توانید از آن برای قرار دادن نشانگرها روی نقشه یا موقعیت روی نقشه استفاده کنید.

نمای کلی سطح بالایی از تفاوت‌های بین Address Validation و Geocoding API را می‌توانید در اینجا ببینید.

اکنون امتحان کنید: به کنسول Google Cloud بروید و Address Validation API و Places API را فعال کنید.

چه زمانی Address Validation را به‌جای Geocoding API انتخاب کنید

نکاتی درباره نمودار جریان بالا:

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

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

در موارد زیر ممکن است انتخاب کنید که از «میانای برنامه‌سازی کاربردی اعتبارسنجی نشانی» به‌جای «میانای برنامه‌سازی کاربردی تبدیل نشانی به مختصات جغرافیایی» استفاده کنید:

• احتمال زیاد وجود داده‌های مشکوک، یا جایی که دریافت نشانی نادرست تأثیر منفی بر جریان پایین‌دستی خواهد داشت. دلیل آن این است که Address Validation API بازخورد بیشتری درباره اینکه چرا ورودی نتیجه‌ای با دقت بالا دریافت نکرده است ارائه می‌دهد.
• باید ورودی‌های کاربر را تصحیح کنید (مثلاً غلط املایی یا فیلدهای جاافتاده)، که احتمال نتیجه دقیق در خروجی را افزایش می‌دهد.
• منطقه هدف شما فراداده بیشتری را از Address Validation API درمقایسه با Geocoding API برمی‌گرداند، مانند طبقه‌بندی نوع ساختمان به‌عنوان مسکونی درمقابل تجاری.

در موارد زیر ممکن است انتخاب کنید که از «کدبندی جغرافیایی» به‌جای «میانای برنامه‌سازی کاربردی اعتبارسنجی نشانی» استفاده کنید:

• هدف اصلی شما بازیابی مکان نشانی است و دقت نشانی‌های فردی ممکن است حیاتی نباشد.
  • برای مثال، ممکن است بخواهید از یک مجموعه داده بزرگ نقشه حرارتی تولید کنید.
• به جزئیات مقصد بسیار محلی نیاز دارید، مثل ورودی‌های ساختمان، طرح‌های کلی ساختمان، یا نقاط ناوبری سوار کردن و پیاده کردن (در Geocoding API نسخه ۴ با روش SearchDestinations دردسترس است).
• به راه‌حل جهانی نیاز دارید و «میانای برنامه کاربردی درستی‌سنجی نشانی» در همه مناطق هدف دردسترس نیست.

در زیر چند مثال آورده شده است که قابلیت‌های Address Validation API را در مقایسه با Geocoding API نشان می‌دهد.

مثال نشانی نامعتبر

1 Fake St, Mountain View, CA 94043, USA

‫Address Validation API این ورودی را به مؤلفه‌های نشانی جداگانه (خیابان، شهر، استان، و غیره) تقسیم می‌کند. همچنین می‌تواند بازخورد دقیقی درباره دلیل نامعتبر بودن نشانی تا سطح PREMISE ارائه دهد.

Fake St در Mountain View، کالیفرنیا وجود ندارد و Address Validation API این موضوع را در جزئیات سطح مؤلفه برگردانده‌شده نشان می‌دهد:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

دارایی مهم برای بازرسی در این مورد confirmationLevel است. با برگرداندن UNCONFIRMED_BUT_PLAUSIBLE درمقابل Fake St، میانای برنامه‌سازی کاربردی تعیین کرده است که ممکن است خیابانی با این نام وجود داشته باشد، اما نمی‌توان آن را با داده‌های نشانی پشتیبانی مطابقت داد.

بااستفاده از نتیجه «میانای برنامه‌سازی کاربردی» به‌عنوان بازخورد، می‌توان نتیجه گرفت که عنصر خیابان این ورودی (Fake St) مشکل دارد.

بااستفاده از همان نشانی با Geocoding API، می‌تواند با «کالیفرنیا» مطابقت دهد، همان‌طور که در نماگرفت ابزار زمین‌کدیابی می‌بینید که می‌توانید آن را اینجا امتحان کنید:

بااین‌حال، نتیجه زمین‌کدیابی کل ایالت است، با حداقل بازخورد درباره اینکه کدام مؤلفه‌ها در ورودی احتمالاً معیوب بوده‌اند.

نمونه غلط املایی

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

نشانی بالا چند غلط املایی دارد، یکی در نام خیابان و دیگری در محل.

هم «API اعتبارسنجی نشانی» و هم «API زمین‌کدیابی» می‌توانند این اشتباهات را اصلاح کنند و به نتیجه 76 Buckingham Palace Road, London, SW1W 9TQ برسند. بااین‌حال، Address Validation API می‌تواند اطلاعات بیشتری درباره این فرایند ارائه دهد.

به یکی از مؤلفه‌های نشانی که در ورودی اشتباه نوشته شده است نگاه کنید:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

«میانای برنامه‌سازی کاربردی درستی‌سنجی نشانی» پرچمی را برمی‌گرداند که نشان می‌دهد فیلد اصلاح شده است. منطق کسب‌وکار می‌تواند درمقابل این پرچم اجرا شود تا تصحیح را با ارائه‌دهنده داده، مثلاً مشتری در تسویه‌حساب تجارت الکترونیک، دوباره بررسی کند.

نمونه خطای املایی و داده‌های ناقص

Bollschestraße 86, 12587, DE

نشانی بالا در نام خیابان غلط املایی دارد و شهر (محل) برلین در آن ذکر نشده است.

«میانای برنامه‌سازی کاربردی اعتبارسنجی نشانی» می‌تواند هر دو این خطا را برطرف کند و یک زمین‌کد سطح PREMISE و نشانی‌ای که تا سطح PREMISE درستی‌سنجی شده است برگرداند:

Bölschestraße 86, 12587 Berlin, DE

Geocoding API در این مورد نمی‌تواند با موفقیت بر خطاهای ورودی غلبه کند و نتیجه ZERO_RESULTS را برمی‌گرداند.

مثال فراداده نشانی اضافی

111 8th Avenue Ste 123, New York, NY 10011-5201, US

این نشانی درست است، به‌جز شماره واحد (Ste 123) که در این ساختمان وجود ندارد.

Address Validation API می‌تواند نشانی را تا PREMISE (111 8th Ave) اعتبارسنجی کند و برخی فراداده‌ها را درباره ملک ارائه دهد، ازجمله اینکه تجاری است

مکان:

"business": true

به‌علاوه، مقدار dpvConfirmation که به‌عنوان بخشی از uspsData در پاسخ برگردانده شده است S است:

"dpvConfirmation": "S"

مقدار dpvConfirmation S نشان می‌دهد که نشانی تا سطح PREMISE اعتبارسنجی شده است، اما شماره واحد ارائه‌شده در ورودی با آن نشانی مرتبط نیست.

‫Geocoding API نمی‌تواند این اطلاعات را ارائه دهد.

درک پاسخ Geocoding API

نمای کلی

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

Geocoding API با حل کردن مؤلفه‌های نشانی در یک سلسله‌مراتب کار می‌کند.

برای **مثال، 123 Example Street, Chicago, 60007, USA به‌ترتیب زیر حل می‌شود:

‫/ Example Street/ Chicago/ 60007/ USA به همین ترتیب ارزیابی خواهد شد. اولین مطابقت در این مورد شیکاگو و به‌طور دقیق‌تر، 60007 «کد پستی» است. بنابراین، Place_id زیر را برای آن کد پستی برمی‌گرداند:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Geocode API حاوی اطلاعات زیر در پاسخ است:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

«میانای برنامه‌سازی کاربردی زمین‌کدگذاری» می‌تواند تأیید کند که این نشانی متعلق به چه نوع مکانی است. فهرست نشانی types که Geocoding API برمی‌گرداند را می‌توانید در اینجا پیدا کنید.

اگر هیچ‌یک از مؤلفه‌های ورودی حل نشود، API این را برمی‌گرداند:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

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

"types": [
  "route"
]

یعنی Geocoding API نتوانسته است شماره خیابان را پیدا کند یا با آن مطابقت دهد.

توجه: برای اینکه بدانید نشانی وجود دارد یا نه، بررسی کنید که آیا هیچ‌یک از پارامترها (مثل types، partial_match, results, status)) در پاسخ «میانای برنامه‌سازی کاربردی زمین‌کدی» تنظیم شده است یا نه. این کار به‌تدریج سطح اطمینان از وجود نشانی را افزایش می‌دهد، اما آن را ۱۰۰٪ دقیق نمی‌کند. به‌همین دلیل به Address Validation API نیاز داریم.

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

نوع مکان

برای درک صحیح این بخش، باید انواع مکان مختلفی را که ممکن است از پاسخ «میانای برنامه‌سازی کاربردی تبدیل نشانی به مختصات جغرافیایی» برگردانده شود درک کنید:

• ROOFTOP نشان می‌دهد که نتیجه برگردانده‌شده زمین‌کدیاب دقیقی است که اطلاعات مکان آن را با دقت نشانی خیابان دراختیار داریم.
• RANGE_INTERPOLATED نشان می‌دهد که نتیجه برگردانده‌شده نشان‌دهنده تقریبی (معمولاً در جاده) است که بین دو نقطه دقیق (مانند تقاطع‌ها) درون‌یابی شده است. نتایج میان‌یابی‌شده معمولاً زمانی برگردانده می‌شوند که زمین‌کدهای پشت‌بامی برای نشانی خیابان دردسترس نباشد.
• GEOMETRIC_CENTER نشان می‌دهد که نتیجه برگردانده‌شده مرکز هندسی نتیجه‌ای مانند چندخطی (مثلاً خیابان) یا چندضلعی (منطقه) است.
• APPROXIMATE نشان می‌دهد که نتیجه برگشتی هیچ‌یک از موارد بالا نیست.

اگر Geocoding API مقدار location_type ROOFTOP یا RANGE_INTERPOLATED را برگرداند، لزوماً به این معنی نیست که نشانی وجود دارد. به‌طور مشابه، اگر Geocoding API با پرچم partial_match تنظیم‌شده روی true برگردد، ممکن است همچنان نتیجه مناسبی برای شما باشد.

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

توجه: اگر تصمیم گرفتید از Geocoding API استفاده کنید، توصیه می‌شود که به‌طور منظم بین درخواست اولیه و پاسخ Geocoding API بررسی‌های کیفیت داده انجام دهید.

مطابقت جزئی و مطابقت نادرست

اگر نشانی مطابقت جزئی داشته باشد، یعنی Geocoding API نتواند نشانی را دقیقاً شناسایی کند، پاسخ حاوی موارد زیر است:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

مهم‌تر از انواع مکان در بالا این است که درنظر بگیرید partial_match = true چه زمانی در پاسخ است. partial_match نشان می‌دهد که Geocoding API مطابقت دقیقی برای درخواست اصلی برنگردانده است، هرچند توانسته است بخشی از نشانی درخواستی را مطابقت دهد.

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

برای مثال، «21 Henr St, Bristol, UK» مطابقت جزئی برای هر دو خیابان Henry و Henrietta برمی‌گرداند. توجه داشته باشید که اگر درخواستی شامل مؤلفه نشانی با املای نادرست باشد، Geocoding API ممکن است نشانی جایگزینی پیشنهاد دهد. پیشنهادهایی که به این روش راه‌اندازی می‌شوند به‌عنوان مطابقت جزئی علامت‌گذاری نخواهند شد.

نشانی‌های مصنوعی

Geocoding API ممکن است مکان‌هایی را برای نشانی‌های «مصنوعی» برگرداند که به‌عنوان مکان‌های دقیق در پایگاه داده Google وجود ندارند.

در چنین سناریوهایی، شیء پاسخ اغلب حاوی یک «شناسه مکان» طولانی و ویژگی زیر است: geometry.location_type=APPROXIMATE.

اگر با این نشانگرها در پاسخ مواجه شدید، لطفاً نشانی ورودی را به‌عنوان نامعتبر علامت‌گذاری کنید و سعی کنید آن را ازطریق روش دیگری دوباره اعتبارسنجی کنید.

توجه: این مثال دیگری است که در آن با «میانای برنامه‌سازی کاربردی درستی‌سنجی نشانی»، اگر نشانی وجود نداشته باشد، بازخورد مستقیم دریافت می‌کنید.

درک پاسخ Address Validation API

مستندات بسیار خوبی درباره نحوه درک پاسخ‌های «میانای برنامه‌سازی کاربردی اعتبارسنجی نشانی» وجود دارد، بنابراین در اینجا به جزئیات بیشتر نمی‌پردازیم.

• نمای کلی از شیء پاسخ را می‌توانید اینجا پیدا کنید.
• نسخه نمایشی که مؤلفه‌های مختلف پاسخ را نشان می‌دهد اینجا است
• در سند «اعتبارسنجی نشانی» برای تسویه‌حساب، شرح مفصلی درباره نحوه تشخیص نشانی‌های خوب از بد وجود دارد.

روال‌های مطلوب

مشخص کردن جغرافیا

هنگام تماس با «میانای برنامه‌سازی کاربردی» «اعتبارسنجی نشانی» یا «زمین‌کدگذاری»، بهتر است محدوده جغرافیایی جستجوی آن نشانی را محدود کنید. این دو API این کار را به دو روش مختلف انجام می‌دهند:

• Geocoding API - Region Biasing

  اگر می‌دانید که زمین‌کدیاب‌ها در کشور خاصی قرار خواهند گرفت، بااستفاده از سوگیری منطقه‌ای نتایج بسیار بهتری دریافت می‌کنید. برای مثال، اگر در کانادا زمین‌کدیابی می‌کنید، توصیه می‌کنیم &region=ca را به درخواست‌هایتان اضافه کنید تا به کانادا متمایل شود. لطفاً توجه داشته باشید که «گرایش منطقه‌ای» فقط نتایج درون آن منطقه را ترجیح می‌دهد. همچنان می‌توانید نتایج خارج از منطقه را دریافت کنید.

• Address Validation API - Region Code

  به‌همین ترتیب، اگر کد ISO2 بااستفاده از فیلد regionCode در درخواست ارسال شود، «میانای برنامه‌سازی کاربردی درستی‌سنجی نشانی» نتایج دقیق‌تری تولید می‌کند.

ذخیره کردن شناسه‌های مکان

برای ذخیره اطلاعات از Google Maps Platform درباره مکان برای درخواست‌های آینده، می‌توانید شناسه مکان را به‌طور نامحدود در پایگاه داده خود به‌عنوان مشخصه مکان ذخیره کنید. فقط باید یک بار برای هر شناسه مکان درخواست یافتن مکان بدهید. همچنین می‌توانید هربار که کاربر جزئیات تراکنش را درخواست می‌کند، شناسه مکان را جستجو کنید.

برای اطمینان از اینکه همیشه به‌روزترین اطلاعات را دارید، هر ۱۲ ماه یک‌بار شناسه‌های مکان را بااستفاده از درخواست جزئیات مکان با پارامتر place_id بازآوری کنید.

توجه: لطفاً حتماً راهنمای روال‌های مطلوب برای «زمین‌کدیابی» را نیز مرور کنید.

نتیجه‌گیری

این سند تفاوت‌های اصلی بین Address Validation API و Geocoding API را شرح می‌دهد. به‌طور خلاصه، در شرایط زیر استفاده از Address Validation API را درنظر بگیرید:

• نشانی پستی دقیق لازم است، به‌ویژه برای اهداف تحویل.
• داده‌های ورودی کیفیت پایینی دارند. Address Validation API دربرابر خطاهای ورودی بخشنده‌تر است، بخش‌های غیرقابل‌تأیید نشانی را برجسته می‌کند، و داده‌های ورودی را اصلاح می‌کند.
• اطلاعات بیشتری برای نشانی لازم است، مثل مسکونی درمقابل تجاری (در مناطق منتخب دردسترس است).

مراحل بعدی

بهبود تسویه‌حساب، ارسال، و عملیات با نشانی‌های مطمئن «کاغذ سفید» را بارگیری کنید و بهبود تسویه‌حساب، ارسال، و عملیات با «درستی‌سنجی نشانی» «وبینار» را مشاهده کنید.

مطالعه بیشتر پیشنهادی:

• اعتبارسنجی نشانی برای تسویه‌حساب تجارت الکترونیک
• مستندات تکمیل خودکار جا
• مستندات Address Validation API
• گزارش‌دهی Google Maps Platform

همیاران

Google این مقاله را نگهداری می‌کند. همیاران زیر در ابتدا آن را نوشته‌اند.

نویسندگان اصلی:

Henrik Valve | مهندس راه‌حل‌ها

توماس آنگلارت | مهندس راه‌حل‌ها

Sarthak Ganguly | مهندس راه‌حل‌ها