«زمین‌کدگذاری» فرایند تبدیل نشانی‌ها (مثل نشانی خیابان) به مختصات جغرافیایی (عرض و طول جغرافیایی) است که می‌توانید از آن برای قرار دادن نشانگرها روی نقشه یا تعیین موقعیت نقشه استفاده کنید. هدف این سند روشن کردن ملاحظات مربوط به زمین‌کدگذاری نشانی‌ها است. این سند توضیح می‌دهد که چه زمانی استفاده از «میانای برنامه‌سازی کاربردی Geocoding» بهینه است و چه زمانی استفاده از سرویس «تکمیل خودکار مکان» در «میانای برنامه‌سازی کاربردی مکان‌ها» مفید است.
به‌طورکلی، هنگام زمین‌کد کردن نشانی‌های کامل (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia»)، از Geocoding API استفاده کنید. از Places API سرویس «تکمیل خودکار مکان» هنگام زمین‌کد کردن نشانی‌های مبهم (ناقص) یا برای کاربردهای حساس به تأخیر، مثل هنگام پاسخ دادن به ورودی کاربر، استفاده کنید.
موارد استفاده و توصیه‌های API
| موارد استفاده و توصیه‌های میانای برنامه‌سازی کاربردی | |
|---|---|
| پاسخ دادن به ورودی کاربر در زمان واقعی (شامل نشانی‌های مبهم، ناقص، با قالب‌بندی ضعیف، یا با املای نادرست که توسط کاربر وارد شده است) | از سرویس «تکمیل خودکار جا» در Places API برای دریافت شناسه جا استفاده کنید، سپس از Geocoding API برای زمین‌کدیابی شناسه جا به طول و عرض جغرافیایی استفاده کنید. |
| سیستم‌های خودکارشده‌ای که نشانی‌های پستی کامل، واضح، و بدون ابهام را پردازش می‌کنند (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia») | از سرویس وب Geocoding API استفاده کنید. |
| سیستم‌های خودکارشده‌ای که پُرسمان‌های مبهم را پردازش می‌کنند (برای نمونه، آدرس‌های ناقص، با قالب‌بندی ضعیف، یا دارای غلط املایی) | توصیه می‌شود سیستم‌های خودکارشده از سرویس وب Geocoding API استفاده کنند. بااین‌حال، سیستم‌های خودکارشده با نرخ بالای پُرسمان‌های مبهم، ناقص، یا دارای غلط املایی که از درونداد کاربر مشتق شده‌اند ممکن است از افزودن ابزاره تعاملی «تکمیل خودکار جا» بهره‌مند شوند تا به کاربران اجازه دهند نتیجه‌ای را انتخاب کنند و درنتیجه از غلط املایی در نشانی جلوگیری شود. |
| مشکلات تأخیر بااستفاده از Directions API (قدیمی) یا Distance Matrix API (قدیمی)، با مبدأها، مقصدها، یا ایستگاه‌های بین راهی که به‌عنوان رشته‌های نشانی مشخص شده‌اند | بااستفاده از سرویس «تکمیل خودکار مکان» در Places API برای دریافت شناسه‌های مکان، سپس انتقال شناسه‌های مکان به Directions API (قدیمی) یا Distance Matrix API (قدیمی)، تأخیر در زمین‌کدگذاری را کاهش دهید. |
پاسخ به ورودی کاربر
برنامه‌هایی که در زمان واقعی به ورودی کاربر پاسخ می‌دهند دو ملاحظه مهم دارند که بر انتخاب API تأثیر می‌گذارد:
- درونداد کاربر معمولاً شامل وارد کردن تدریجی نشانی است (مانند «123 Main Street»)، بنابراین توانایی زمین‌کدیابی نشانی‌های ناقص و مبهم مفید است زیرا به کاربر امکان می‌دهد سریع‌تر نتیجه بگیرد.
- برنامه‌هایی که به ورودی کاربر پاسخ می‌دهند به تأخیر بسیار حساس هستند.
این دو ملاحظه باعث می‌شود «سرویس تکمیل خودکار مکان» در «میانای برنامه‌سازی کاربردی مکان‌ها» برای مورد استفاده پاسخ دادن به ورودی کاربر ایده‌آل باشد. «تکمیل خودکار مکان» برای برگرداندن چندین گزینه ممکن و اجازه دادن به کاربر برای انتخاب بین آن‌ها طراحی شده است. «میانای برنامه‌سازی کاربردی مکان‌ها» می‌تواند محدود شود تا فقط کدهای جغرافیایی یا نشانی‌ها را جستجو کند و کسب‌وکارها را مستثنا کند. علاوه‌براین، تابع جستجوی تکمیل خودکار می‌تواند برای برگرداندن نتایج مختص یک مکان، سوگیری داشته باشد. Places API شناسه مکان را برمی‌گرداند که می‌تواند به‌عنوان مکان کاملاً شفاف به سرویس وب Geocoding API منتقل شود، که سپس جزئیات کامل نشانی را برمی‌گرداند و نشانی را به latlng زمین‌کد می‌کند. شناسه‌های مکان را می‌توان به میاناهای برنامه‌سازی کاربردی دیگر نیز منتقل کرد، برای مثال، Directions API (قدیمی) و Distance Matrix API (قدیمی) (به کاهش تأخیر مراجعه کنید).
زمینه‌کدیابی نشانی در Geocoding API تأخیر بسیار بیشتری دارد و همچنین نتایج با دقت کمتری برای پُرسمان‌های ناقص یا مبهم تولید می‌کند، بنابراین برای برنامه‌هایی که باید در زمان واقعی به ورودی کاربر پاسخ دهند توصیه نمی‌شود.
اطلاعات بیشتر درباره سرویس «تکمیل خودکار جا» برای Android، iOS، JavaScript، و Places API دریافت کنید.
سیستم‌های خودکارسازی‌شده
سیستم‌های خودکارشده‌ای که نشانی‌های پستی کامل و بدون ابهام را پردازش می‌کنند: پُرسمان‌های بدون ابهام مانند رشته‌های نشانی پستی کامل (برای مثال، «48 Pirrama Rd, Pyrmont, NSW, Australia») بهتر است توسط سرویس وب Geocoding API مدیریت شوند. پشتیبان زمین‌کدیابی نشانی پوشش جهانی بیشتری از نشانی‌ها ارائه می‌دهد، و برای نتایج با کیفیت بالا با این نوع پُرسمان‌های کامل و بدون ابهام بهینه‌سازی شده است.
پردازش خودکار سیستم برای پُرسمان‌های مبهم: پُرسمان‌های مبهم پُرسمان‌هایی هستند که حاوی نشانی‌های با قالب‌بندی نادرست، نشانی‌های ناتمام، یا غلط املایی هستند. برای سیستم‌های خودکار، توصیه می‌کنیم از خدمات وب «میانای برنامه کاربردی Geocoding» استفاده کنید. بااین‌حال، 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 (Legacy) یا Distance Matrix API (Legacy) در شرایط حساس به تأخیر مانند پاسخ به ورودی کاربر استفاده می‌کند، و مبدأ، مقصد، یا نقطه‌مسیرهای شما در ابتدا به‌عنوان رشته‌های نشانی مشخص شده‌اند، توصیه می‌کنیم بااستفاده از سرویس «تکمیل خودکار جا» در Places API برای تبدیل رشته‌های نشانی به شناسه‌های جا، تأخیر را به‌حداقل برسانید، سپس شناسه‌های جا را به Directions API (Legacy) یا Distance Matrix API (Legacy) ارسال کنید. اطلاعات بیشتری درباره سرویس «تکمیل خودکار جا» برای 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» کتابخانه‌های مشتری پشتیبانی‌شده توسط انجمن هستند که برای بارگیری
و مشارکت در GitHub دردسترس هستند، جایی که دستورالعمل‌های نصب و
کد نمونه را نیز پیدا خواهید کرد.
اگر کد وضعیت OVER_QUERY_LIMIT را به‌عنوان پاسخ دریافت کردید،
از حدود استفاده برای این «میانای برنامه‌سازی کاربردی» فراتر رفته‌اید. توصیه می‌کنیم
این
راهبردهای بهینه‌سازی استفاده را امتحان کنید.