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

هدف اصلی

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

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

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

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

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

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

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

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

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

در شرایط زیر ممکن است Address Validation API را به Geocoding API ترجیح دهید:

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

در شرایط زیر ممکن است انتخاب کنید که از Geocoding به‌جای Address Validation API استفاده کنید:

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

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

نمونه نشانی نامعتبر

1 Fake St, Mountain View, CA 94043, USA

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

Fake St در Mountain View، CA وجود ندارد و 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، می‌تواند با «کالیفرنیا» مطابقت دهد، همان‌طور که در نماگرفت زیر از ابزار Geocoder نشان داده شده است:

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

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

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

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

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

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

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

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

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

Bollschestraße 86, 12587, DE

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

Address Validation API می‌تواند هر دو این خطاها را برطرف کند و زمین‌کدیابی سطح 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"
           ]

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

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

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

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

"types": [
  "route"
]

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

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

می‌توانید از روش‌های بالا برای افزایش اطمینان از دقت نشانی فقط از پاسخ Geocoding API استفاده کنید. بااین‌حال، برخلاف نتیجه Address Validation API، Geocoding 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، اگر نشانی وجود نداشته باشد، بازخورد مستقیم دریافت می‌کنید.

درک پاسخ Address Validation API

درحال‌حاضر مستندات بسیار خوبی درباره نحوه درک پاسخ‌های Address Validation API وجود دارد، بنابراین در اینجا به جزئیات بیشتر نمی‌پردازیم.

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

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

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

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

• Geocoding API - Region Biasing

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

• Address Validation API - Region Code

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

ذخیره کردن شناسه جا

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

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

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

نتیجه‌گیری

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

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

مراحل بعدی

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

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

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

همیاران

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

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

هنریک والو | مهندس راه‌حل‌ها

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

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