המרת כתובות לקואורדינטות (geocoding) היא תהליך של המרת כתובות (כמו כתובת רחוב) לקואורדינטות גיאוגרפיות (קווי רוחב וקווי אורך) שבהן אפשר להשתמש כדי להציב סמנים במפה או למקם את המפה. המסמך הזה מתמקד בהבהרת השיקולים שצריך להביא בחשבון כשמבצעים המרת כתובות לקואורדינטות. הוא מתאר מתי הכי כדאי להשתמש ב-Geocoding API ומתי כדאי להשתמש בשירות ההשלמה האוטומטית למקומות של Places API.
באופן כללי, כדאי להשתמש ב-Geocoding API כשממירים כתובות מלאות (לדוגמה, "48 Pirrama Rd, Pyrmont, NSW, Australia"). כדאי להשתמש בשירות ההשלמה האוטומטית למקומות של Places API כשמבצעים המרה של כתובות לא ברורות (לא מלאות) לקואורדינטות, או באפליקציות שרגישות לזמן האחזור, למשל כשמגיבים לקלט של משתמשים.
תרחישים לדוגמה והמלצות לשימוש ב-API
| תרחישים לדוגמה והמלצות לשימוש ב-API | |
|---|---|
| הגעה פיזית, בחירת יעד מתקדמת, משלוח בשלב האחרון, איסוף/הורדה של נסיעה שיתופית, כניסות לבניינים או ניווט בקמפוס | כדי לאחזר כניסות לבניינים, נקודות ניווט שניתן לנתב אליהן, קווי מתאר של בניינים וציוני דרך בקרבת מקום, משתמשים ב-method Search for destinations (SearchDestinations) ב-Geocoding API v4. בחירת שיטה להמרת כתובות לקואורדינטות |
| להגיב בזמן אמת לקלט של משתמשים (כולל כתובות שהמשתמשים הזינו והן לא ברורות, חלקיות, בפורמט שגוי או עם שגיאות כתיב) | משתמשים בשירות השלמה אוטומטית למקומות של 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 (מדור קודם). |
להגיב לקלט של משתמשים
באפליקציות שמגיבות בזמן אמת לקלט של המשתמש, יש שני שיקולים עיקריים שמשפיעים על בחירת ה-API:
- בדרך כלל, המשתמשים מזינים את הכתובת בהדרגה (למשל, "רחוב הרצל 123"), ולכן היכולת להמיר לקואורדינטות כתובות חלקיות או לא ברורות מאפשרת למשתמשים לקבל תוצאה מהר יותר.
- אפליקציות שמגיבות לקלט של משתמשים רגישות מאוד לזמן אחזור.
שני השיקולים האלה הופכים את שירות ההשלמה האוטומטית למקומות ב-Places API לאידיאלי לתרחיש השימוש של תגובה לקלט של משתמשים. ההשלמה האוטומטית למקומות נועדה להחזיר כמה אפשרויות ולאפשר למשתמש לבחור ביניהן. אפשר להגביל את Places API כך שיחפש רק קואורדינטות או כתובות, ולא יכלול עסקים. בנוסף, אפשר להטות את פונקציית החיפוש של ההשלמה האוטומטית כדי להחזיר תוצאות ספציפיות למיקום. Places API מחזיר מזהה מקום שאפשר להעביר כמיקום חד-משמעי לשירות האינטרנט Geocoding API. לאחר מכן, השירות מחזיר את פרטי הכתובת המלאים וממיר את הכתובת לקואורדינטות של קו רוחב וקו אורך. אפשר גם להעביר מזהי מקומות לממשקי API אחרים, כמו Directions API (מדור קודם) ו-Distance Matrix API (מדור קודם) (ראו צמצום זמן האחזור).
המרת כתובות לקואורדינטות ב-Geocoding API מתבצעת עם זמן אחזור ארוך בהרבה, וגם מניבה תוצאות פחות מדויקות לשאילתות חלקיות או לא ברורות, ולכן לא מומלץ להשתמש בה באפליקציות שצריכות להגיב בזמן אמת לקלט של משתמשים.
מידע נוסף על שירות ההשלמה האוטומטית למקומות ב-Android, ב-iOS, ב-JavaScript וב- Places API.
מערכות אוטומטיות
מערכות אוטומטיות שמעבדות כתובות דואר מלאות וחד-משמעיות: שאילתות חד-משמעיות כמו מחרוזות של כתובות דואר מלאות (לדוגמה, "48 Pirrama Rd, Pyrmont, NSW, Australia") מטופלות בצורה הטובה ביותר על ידי שירות האינטרנט של Geocoding API. ה-backend של המרת הכתובות לקואורדינטות מספק כיסוי רחב יותר של כתובות ברחבי העולם, והוא מותאם לתוצאות באיכות גבוהה עם שאילתות מלאות וחד-משמעיות מהסוגים האלה.
מערכת אוטומטית שמעבדת שאילתות לא ברורות: שאילתות לא ברורות הן שאילתות שמכילות כתובות בפורמט לא תקין, כתובות חלקיות או שגיאות כתיב. במערכות אוטומטיות, מומלץ להשתמש ב שירות האינטרנט של Geocoding API. עם זאת, Geocoding API לא נועד להתמודד עם שאילתות לא ברורות, והוא עלול להפיק תוצאות פחות מדויקות או לא להפיק תוצאות בכלל בתגובה לשאילתות כאלה. אם המערכת האוטומטית שלכם מעבדת שיעור גבוה של שאילתות לא ברורות שמקורן בקלט של משתמשים, יכול להיות שכדאי לכם להוסיף רכיב אינטראקטיבי לאפליקציה באמצעות שירות ההשלמה האוטומטית למקומות ב-Places API, כי הוא נועד להחזיר כמה אפשרויות ולאפשר למשתמש לבחור ביניהן. Places API מחזיר מזהה מקום שאפשר להעביר בתור מיקום חד-משמעי לשירות האינטרנט Geocoding API, שמחזיר את פרטי הכתובת המלאים וממיר את הכתובת לקואורדינטות של קו רוחב וקו אורך. מידע נוסף על שירות ההשלמה האוטומטית למקומות ב-Android, ב-iOS, ב-JavaScript וב- Places API.
צמצום זמן האחזור ב-Directions API (הגרסה הקודמת) וב-Distance Matrix API (הגרסה הקודמת)
כשמציינים נקודות מוצא, נקודות יעד או נקודות דרך כמחרוזות של כתובות, ממשקי ה-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. אפשר גם לעיין ב דוגמה ב-JavaScript להשלמה אוטומטית של מקומות ומסלולי הגעה.
סיכום
בהתאם לתרחיש לדוגמה, אתם יכולים להשתמש ב-Geocoding API לבד או לשלב אותו עם השירות "השלמה אוטומטית למקומות". כך אפשר לפתח אפליקציות שמציעות תוצאות מדויקות של המרת כתובות לקואורדינטות וזמן אחזור קצר יותר.
ניהול שגיאות וניסיונות חוזרים
אם מתקבלות תגובות UNKNOWN_ERROR, הן נגרמות בגלל שגיאות זמניות, והדרך הכי טובה לטפל בהן היא לנסות שוב אחרי השהיה קצרה. אנחנו ממליצים להשתמש ב
ספריות הלקוח של שירותי האינטרנט של הפלטפורמה של מפות Google, שכוללות לוגיקה של ניסיון חוזר ותומכות באימות של תוכנית הפרימיום של הפלטפורמה של מפות Google.
Java Client, Python Client, Go Client ו-Node.js Client לשירותי מפות Google הן ספריות לקוח שנתמכות על ידי הקהילה. אפשר להוריד אותן ולתרום להן ב-GitHub, שם גם תמצאו הוראות התקנה וקוד לדוגמה.
אם קיבלתם קוד סטטוס OVER_QUERY_LIMIT בתגובה, סימן שחרגתם ממגבלות השימוש ב-API. מומלץ לנסות את
האסטרטגיות האלה לאופטימיזציה של השימוש.