زمین‌کدیابی فرایند تبدیل نشانی‌ها (مانند نشانی خیابان) به مختصات جغرافیایی (طول و عرض جغرافیایی) است که می‌توانید از آن برای قرار دادن نشانگرها روی نقشه یا تعیین موقعیت نقشه استفاده کنید. تمرکز این سند بر شفاف‌سازی ملاحظات مربوط به زمین‌کدیابی نشانی‌ها است. این مقاله توضیح می‌دهد که چه زمانی استفاده از Geocoding API بهینه است و چه زمانی استفاده از سرویس «تکمیل خودکار جا» در Places API مفید است.
به‌طور کلی، هنگام زمین‌کدیابی نشانی‌های کامل (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia»)، از Geocoding API استفاده کنید. هنگام زمین‌کدیابی نشانی‌های مبهم (ناقص) یا برای برنامه‌های حساس به تأخیر، مانند هنگام پاسخ دادن به ورودی کاربر، از سرویس تکمیل خودکار جا در Places API استفاده کنید.
موارد استفاده و توصیه‌های میانای برنامه‌سازی کاربردی
| موارد استفاده و توصیه‌های میانای برنامه‌سازی کاربردی | |
|---|---|
| رسیدن فیزیکی، انتخاب مقصد پیشرفته، تحویل مایل آخر، سوار/ پیاده کردن مسافر در سفر اشتراکی، ورودی‌های ساختمان، یا ناوبری پردیس دانشگاه | از روش جستجوی مقصد (SearchDestinations) در Geocoding API نسخه ۴ برای بازیابی ورودی‌های ساختمان، نقاط ناوبری قابل‌یابی، طرح‌های کلی ساختمان، و نشانگرهای مکانی اطراف استفاده کنید. انتخاب روش زمین‌کدیابی را ببینید. |
| پاسخ دادن به ورودی کاربر در زمان واقعی (شامل نشانی‌های مبهم، ناقص، با قالب‌بندی ضعیف، یا دارای غلط املایی که کاربر وارد کرده است) | از سرویس «تکمیل خودکار جا» در Places API برای دریافت شناسه جا استفاده کنید، سپس با SearchDestinations (برای جزئیات محلی) یا GeocodePlace (برای مختصات پایه) تماس بگیرید. |
| سیستم‌های خودکارشده‌ای که نشانی‌های پستی کامل و بدون ابهام را پردازش می‌کنند (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia») | از سرویس وب Geocoding API v4 (SearchDestinations برای جزئیات محلی یا GeocodeAddress برای جستجوی مختصات) استفاده کنید. |
| سیستم‌های خودکارشده که پُرسمان‌های مبهم را پردازش می‌کنند (برای مثال، نشانی‌های ناقص، با قالب‌بندی ضعیف، یا دارای غلط املایی) | توصیه می‌شود سیستم‌های خودکارشده از سرویس وب Geocoding API استفاده کنند. بااین‌حال، سیستم‌های خودکارسازی‌شده با نرخ بالای پُرسمان‌های مبهم، ناقص، یا دارای غلط املایی که از ورودی کاربر مشتق شده‌اند ممکن است از افزودن ابزاره تکمیل خودکار جا تعاملی بهره‌مند شوند تا به کاربران اجازه دهند نتیجه‌ای را انتخاب کنند و درنتیجه از غلط املایی در نشانی جلوگیری شود. |
| مشکلات تأخیر هنگام استفاده از Directions API (قدیمی) یا Distance Matrix API (قدیمی) با مبدأ، مقصد، یا نقطه‌مسیرهای مشخص‌شده به‌عنوان رشته‌های نشانی | بااستفاده از سرویس «تکمیل خودکار جا» در Places API برای دریافت شناسه‌های جا، تأخیر زمین‌کدیابی را کاهش دهید، سپس «شناسه‌های جا» را به Directions API (قدیمی) یا Distance Matrix API (قدیمی) ارسال کنید. |
پاسخ دادن به ورودی کاربر
برنامه‌هایی که در زمان واقعی به ورودی کاربر پاسخ می‌دهند دو ملاحظه اصلی دارند که بر انتخاب میانای برنامه‌سازی کاربردی تأثیر می‌گذارد:
- درونداد کاربر معمولاً شامل وارد کردن تدریجی نشانی است (مانند «123 Main Street»)، بنابراین توانایی زمین‌کدیابی نشانی‌های ناقص و مبهم مفید است زیرا به کاربر امکان می‌دهد سریع‌تر نتیجه بگیرد.
- برنامه‌هایی که به ورودی کاربر پاسخ می‌دهند به‌شدت به تأخیر حساس هستند.
این دو ملاحظه باعث می‌شود سرویس «تکمیل خودکار جا» در Places API برای مورد استفاده پاسخ دادن به ورودی کاربر ایده‌آل باشد. «تکمیل خودکار جا» برای برگرداندن چند گزینه احتمالی و امکان انتخاب بین آن‌ها برای کاربر طراحی شده است. Places API را می‌توان محدود کرد تا فقط زمین‌کدها یا نشانی‌ها را جستجو کند و کسب‌وکارها را مستثنی کند. علاوه‌براین، عملکرد جستجوی تکمیل خودکار می‌تواند برای برگرداندن نتایج مختص یک مکان سوگیری داشته باشد. Places API شناسه مکانی را برمی‌گرداند که می‌تواند به‌عنوان مکانی کاملاً ابهام‌زدایی‌شده به سرویس وب Geocoding API ارسال شود، که سپس جزئیات کامل نشانی را برمی‌گرداند و نشانی را به طول و عرض جغرافیایی زمین‌کدیابی می‌کند. شناسه‌های جا را می‌توان به میاناهای برنامه‌سازی کاربردی دیگر نیز ارسال کرد، مثلاً Directions API (Legacy) و Distance Matrix API (Legacy) (به کاهش تأخیر مراجعه کنید).
زمینه‌کدیابی نشانی در Geocoding API تأخیر بسیار بیشتری دارد و همچنین نتایج با دقت کمتری برای پُرسمان‌های ناقص یا مبهم تولید می‌کند، بنابراین برای برنامه‌هایی که باید در زمان واقعی به ورودی کاربر پاسخ دهند توصیه نمی‌شود.
اطلاعات بیشتری درباره سرویس «تکمیل خودکار جا» برای Android، iOS، JavaScript، و Places API دریافت کنید.
سیستم‌های خودکارسازی‌شده
سیستم‌های خودکارشده که نشانی‌های پستی کامل و بدون ابهام را پردازش می‌کنند: پُرسمان‌های بدون ابهام مانند رشته‌های نشانی پستی کامل (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia») بهتر است توسط سرویس وب Geocoding API مدیریت شوند. بخش پشتی زمین‌کدیابی نشانی پوشش بیشتری از نشانی‌ها را در سطح جهانی ارائه می‌دهد، و برای نتایج با کیفیت بالا با این نوع پُرسمان‌های کامل و بدون ابهام بهینه‌سازی شده است.
سیستم خودکارسازی‌شده‌ای که پُرسمان‌های مبهم را پردازش می‌کند: پُرسمان‌های مبهم پُرسمان‌هایی هستند که حاوی نشانی‌هایی با قالب‌بندی ضعیف، نشانی‌های ناقص، یا غلط‌های املایی هستند. برای سیستم‌های خودکار، توصیه می‌کنیم از سرویس وب Geocoding API استفاده کنید. بااین‌حال، Geocoding API برای مقابله با پُرسمان‌های مبهم طراحی نشده است و ممکن است در پاسخ به پُرسمان‌های مبهم، نتایج با دقت کمتر یا بدون نتیجه تولید کند. اگر سیستم خودکارشده شما نرخ بالایی از پُرسمان‌های مبهم را که از ورودی کاربر مشتق شده‌اند پردازش می‌کند، ممکن است بااستفاده از سرویس «تکمیل خودکار جا» در Places API، از افزودن عنصر تعاملی به برنامه‌تان بهره‌مند شوید، زیرا این سرویس برای برگرداندن چندین گزینه ممکن و اجازه دادن به کاربر برای انتخاب بین آن‌ها طراحی شده است. Places API یک شناسه مکان برمی‌گرداند که می‌تواند به‌عنوان یک مکان کاملاً ابهام‌زدایی‌شده به سرویس وب Geocoding API ارسال شود، که سپس جزئیات کامل نشانی را برمی‌گرداند و نشانی را به یک latlng زمین‌کدیابی می‌کند. اطلاعات بیشتری درباره سرویس «تکمیل خودکار جا» برای Android، iOS، JavaScript، و Places API دریافت کنید.
کاهش تأخیر برای Directions API (قدیمی) و Distance Matrix API (قدیمی)
وقتی مبدأ، مقصد، یا نقطه‌مسیر به‌صورت رشته نشانی مشخص می‌شود، Directions API (قدیمی) و Distance Matrix API (قدیمی) از همان پس‌زمینه‌ای استفاده می‌کنند که Geocoding API برای زمین‌کدیابی این نشانی‌ها قبل‌از محاسبه مسیرها استفاده می‌کند. این کار درمقایسه با مشخص کردن همان مکان‌ها به‌صورت طول و عرض جغرافیایی یا شناسه مکان، تأخیر را به‌طور قابل‌توجهی افزایش می‌دهد.
اگر برنامه شما از Directions API (قدیمی) یا Distance Matrix API (قدیمی) در شرایط حساس به تأخیر استفاده می‌کند، مثلاً پاسخ دادن به ورودی کاربر، و مبدأ، مقصد، یا نقطه‌مسیرهای شما در ابتدا به‌صورت رشته‌های نشانی مشخص شده‌اند، توصیه می‌کنیم بااستفاده از سرویس «تکمیل خودکار جا» در Places API برای تبدیل رشته‌های نشانی به شناسه‌های جا، تأخیر را به‌حداقل برسانید، سپس شناسه‌های جا را به Directions API (قدیمی) یا Distance Matrix API (قدیمی) ارسال کنید. اطلاعات بیشتری درباره سرویس «تکمیل خودکار جا» برای Android، iOS، JavaScript، و Places API دریافت کنید. همچنین نمونه جاوا اسکریپت تکمیل خودکار جا و مسیرها را ببینید.
نتیجه‌گیری
بسته به مورد استفاده‌تان، می‌توانید از Geocoding API به‌تنهایی استفاده کنید یا آن را با سرویس «تکمیل خودکار جا» ترکیب کنید. این کار به شما امکان می‌دهد برنامه‌هایی بسازید که نتایج زمین‌کدیابی دقیق و تأخیر کمتری ارائه می‌دهند.
مدیریت خطاها و تلاش‌های مجدد
اگر پاسخ‌های UNKNOWN_ERROR دریافت می‌کنید، این پاسخ‌ها به‌دلیل خطاهای گذرا ایجاد می‌شوند
و بهترین راه برای مقابله با آن‌ها امتحان مجدد پس‌از تأخیری کوتاه است. توصیه می‌کنیم از
کتابخانه‌های مشتری
سرویس‌های وب «پلاتفرم Google Maps» استفاده کنید که شامل منطق تکرار مجدد است و از اصالت‌سنجی
«طرح Google Maps Platform Premium» پشتیبانی می‌کند.
Java Client،
Python Client،
Go Client،
و Node.js Client
برای Google Maps Services کتابخانه‌های مشتری پشتیبانی‌شده توسط انجمن هستند که برای بارگیری
و مشارکت در GitHub دردسترس هستند، جایی که دستورالعمل‌های نصب و
کد نمونه را نیز پیدا خواهید کرد.
اگر رمز وضعیت OVER_QUERY_LIMIT را به‌عنوان پاسخ دریافت کردید،
از حد استفاده برای میانای برنامه‌سازی کاربردی فراتر رفته‌اید. توصیه می‌کنیم
این
راهبردهای بهینه‌سازی مصرف را امتحان کنید.