טיפים ליצירת חוויית המשתמש הטובה ביותר במהלך ניווט למיקומים עם מכונית

המסמך הזה הוא עדכון של מאמר קודם שנעשה בו שימוש בגרסאות קודמות של ממשקי ה-API של GMP. התוכן הזה מעודכן לגרסה החדשה של Places API, שהושקה בשנים 2023-2024, ול-Routes API, שהושקה בשנת 2023.

בדרך כלל, כשמשתמשים נוסעים לנקודת עניין (POI), הם זקוקים למעשה לניווט למיקום סמוך, כמו חניון או נקודת גישה. נניח שנוסע צריך להגיע לשדה תעופה או לקניון. כשנוסעים לנמל תעופה, הנהג מנסה להגיע לטרמינל או לנקודת הורדה ולא למרכז המתחם של נמל התעופה. באופן דומה, למשתמש עם רכב, חניה ליד מרכז הקניות עשויה להיות אפשרות טובה יותר. במקרה כזה, כשמפתחים אפליקציה או שירות שמפנה את הנהג, קודם צריך למצוא את המיקום שאליו הוא נוסע ואז להציע לו יעדים אופציונליים בסביבה. הגישה הזו מאפשרת לכם לספק שירות טוב יותר ללקוחות ולהראות שאתם מעריכים את הזמן שלהם, תוך מאמץ פיתוח קטן אך חכם שמנצל את נתוני המיקום שסופקו על ידי הפלטפורמה של מפות Google.

נראה איך משתמשים ב-Places API החדש וב-Routes API ברצף או בשילוב כדי לזהות את המיקום הנכון לחניה ליד היעד. הפתרון הזה נועד להסיר את אי-הוודאות ואת הצורך לבצע מספר אינטראקציות כדי למצוא מקום חנייה בזמן הנסיעה, ככל שמתקרבים ליעד הסופי. ריכזנו כאן שתי דוגמאות מפורטות לאופן שבו אפשר ליישם את המקרים האלה.

דוגמה 1 – אטרקציה תיירותית ללא חניון

בוחרים מיקום שלא מקושר ישירות לצד הכביש, כדי שצריך לאחזר מסלול בנפרד. היעד הוא נוטרדאם בפריז, וכנקודת ההתחלה נשתמש בתחנת הרכבת Gare de l'Est (48.87697775149635, 2.3592247806755564).

הנהג יוצא מהתחנה כ-16 דקות צפונית לנוטרדאם. קתדרלת Notre Dame היא אטרקציה תיירותית מפורסמת שנמצאת באי עם גישה דרך גשר, עם כמה רחובות חד-כיווניים וללא מגרש חניה גדול בקרבת מקום, כך שזו אמורה להיות משימה מעניינת.

1. בקשה ל-Places API

בבקשה לדוגמה הזו של Places API נעשה שימוש בחיפוש טקסט כדי למצוא את קתדרלת נוטרדאם. פרטים נוספים זמינים במסמכי התיעוד למפתחים. הערך '$APIKEY' בדוגמאות האלה הוא מפתח ה-API שיש לכם לממשקי ה-API של מפות Google למקומות ולמסלולים, שמופעלים במסוף Google Cloud. הסבר מפורט יותר זמין במסמכי העזרה בנושא תחילת העבודה עם הפלטפורמה של מפות Google.

לבקשות החדשות של Places API יש פורמט חדש. שדות התגובה כבר לא קבועים, וכמפתחים אתם צריכים להגדיר מסכת שדות בכותרת. השימוש במסכת השדות מוגדר במסמכי העזרה.

curl -X POST --data @notre_dame.json \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location' \
'https://places.googleapis.com/v1/places:searchText'

עם תוכן של 'notre_date.json' לפרמטר החיפוש:

{
   "textQuery": "Notre Dame, Paris",
   "languageCode": "en"
}

התגובה לבקשה שלמעלה כוללת את קו הרוחב וקו האורך הבאים:

{
  "places": [
    {
      "id": "ChIJATr1n-Fx5kcRjQb6q6cdQDY",
      "formattedAddress": "6 Parvis Notre-Dame - Pl. Jean-Paul II, 75004 Paris, France",
      "location": {
        "latitude": 48.852968200000007,
        "longitude": 2.3499021
      },
      "displayName": {
        "text": "Cathédrale Notre-Dame de Paris",
        "languageCode": "en"
      }
    }
  ]
}

כפי שאפשר לראות, הקואורדינטות מצביעות אכן על קתדרלת נוטרדאם.

כמפתחים או ספקי שירות, מומלץ להציג לנהגים באופן אוטומטי את ההודעה "מחפשים חניה ליד Notre Dame?". אם לנהג יש רכב חשמלי, כדאי לחפש תחנת טעינה. חוויית המשתמש תשתנה בהתאם למכשיר ולמסך, אבל כדאי לשקול להציג טקסט של תיבת דו-שיח עדין שנעלם אחרי זמן קצר. כדי למצוא חנייה ליד קתדרלת Notre Dame, מבצעים חיפוש בקרבת מקום ב-Places API עם הסוגים 'חניה' ו-'תחנת טעינה לרכב חשמלי' ברדיוס של 500 מטרים. הדוגמה הבאה תגרום להטיה של התוצאות לאזורי חניה במרחק של עד 500 מטר מנוטרדאם.

curl -X POST -d '{
  "includedTypes": ["parking", "electric_vehicle_charging_station"],
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 48.852968200000007,
        "longitude": 2.3499021},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H "X-Goog-FieldMask: places.displayName,places.location" \
https://places.googleapis.com/v1/places:searchNearby

התוצאה הראשונה היא תחנת טעינה ב-48.854981, 2.350629, אבל יכול להיות שהתוצאות שלכם יהיו שונות כשתריצו את הדוגמה הזו. נשתמש במיקום הזה בחלק הבא, שבו נשלח בקשה ל-Routes API.

1. **בקשת Routes API **

כדי למצוא את המסלול מהתחנה לתחנת טעינה ליד קתדרלת נוטרדאם, צריך לשלוח בקשה ל-Routes API. פשוט מגדירים את הפרמטרים של המקור והיעד. אפשרויות נוספות מפורטות במסמכי התיעוד למפתחים.

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 48.87697775149635,
        "longitude": 2.3592247806755564
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
       "latitude": 48.854981,
        "longitude": 2.350629
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "departureTime": "2024-05-16T15:01:23.045123456Z",
  "computeAlternativeRoutes": false,
  "routeModifiers": {
    "avoidTolls": false,
    "avoidHighways": false,
    "avoidFerries": false
  },
  "languageCode": "en-US",
  "units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

התגובה של Routes API מכילה בדרך כלל כמה הצעות למסלולים. כדי לכלול את נתוני המסלול בתגובה, מגדירים את 'routes.legs' במסכת השדות. כל מסלול מורכב מכמה 'קטעים', שכוללים כמה 'שלבים' שבהם מוצגים המרחק והקואורדינטות של המסלול. כדי למצוא את הקואורדינטות הסופיות שאפשר להגיע אליהן ברכב, משתמשים בשדה endLocation בשלב האחרון של הקטע האחרון במסלול שבחרתם. "latitude": 48.854937299999996, "longitude": 2.3505841999999997

המיקום הזה אולי לא נראה כמו הבחירה הראשונה, אבל אם תסתכלו במפה או ב-Google Street View, תראו שהוא נמצא במרחק הליכה קצר מאוד, כ-6-7 דקות, מקתדרלת נוטרדאם.

מסלול הליכה ממקום החניה של תחנת הטעינה לקתדרלת נוטרדאם

סיכום לדוגמה 1

כפי שאפשר לראות, כדי למצוא מקום חניה לרכב נדרשות רק כמה קריאות ל-API והצגת ההצעה לנהג. כך המשתמשים חוסכים זמן, כי הם לא צריכים לנסוע ברחובות חד-סטריים או לחפש מקום להחנות את הרכב באטרקציה תיירותית עמוסה. לסיכום, ביצענו את בקשות ה-API הבאות:

• בקשת חיפוש טקסט ב-Places API כדי למצוא את הקואורדינטות של קתדרלת נוטרדאם
• חיפוש בקרבת מקום ב-Places API כדי למצוא חניון עם תחנת טעינה לרכב חשמלי בטווח של 500 מטרים מהקואורדינטות האלה
• בקשה ל-Routes API כדי למצוא מסלול לתחנת הטעינה

דוגמה 2 – קבלת הנחיות לטרמינל בשדה תעופה גדול

דוגמה נוספת היא מצב שבו הנהג מנסה להגיע לאזור גדול שיש בו כמה מיקומים, נקודות עניין או נקודות מסירה פוטנציאליות. הנהג יוצא מאצטדיון וומבלי, בריטניה (51.557263604707224, -0.2794575145680608) ומנסה להגיע לטרמינל 5 של נמל התעופה לונדון הית'רו.

היתרון הגדול של ההשלמה האוטומטית החדשה של Places API הוא היכולת להגדיר סוג ראשי כקריטריון חיפוש בשילוב עם API שמנבא נכסי משנה כתוצאות חיפוש פוטנציאליות. במקרה כזה, חיפוש של שדה תעופה יוביל גם לתוצאות של מסופים. הרשימה המלאה של הסוגים שאפשר לכלול או להחריג מופיעה במסמכי העזרה.

curl -X POST -d '{
  "input": "Heathrow",
  "includedPrimaryTypes": ["airport"]
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
https://places.googleapis.com/v1/places:autocomplete

השאילתה שלמעלה מספקת לנו רשימה של מסופי האוטובוסים ונקודות האיסוף הספציפיות במסופים האלה. ברשימת התוצאות אפשר למצוא את 'טרמינל 5 של נמל התעופה לונדון הית'רו' ואת מזהה המקום שלו:

"place_id" : "ChIJo21hnPxxdkgRksRL0KQRWII",

באמצעות הפרמטר placeId אנחנו יכולים להודיע ל-Routes API שאנחנו מנסים להגיע למקום מסוים ולא לקואורדינטות שרירותיות.

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 51.557263604707224,
        "longitude": -0.2794575145680608
      }
    }
  },
  "destination":{
    "placeId": "ChIJo21hnPxxdkgRksRL0KQRWII"
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "departureTime": "2024-05-16T15:01:23.045123456Z",
  "computeAlternativeRoutes": false,
  "languageCode": "en-US",
  "units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

שוב, כמו בדוגמה הקודמת, קריאת כל השלבים בתשובת ה-JSON תאפשר לכם למצוא את החלק האחרון של המסלול ואת קו הרוחב וקו האורך של מיקומי הסיום (51.4714348, "longitude": -0.48967890000000003).

סיכום לדוגמה 2

בדומה לדוגמה הקודמת, מאמצי הפיתוח כדי לספק לנהיגה הנחיות משופרות הם קטנים מאוד, והיתרונות של חיסכון הזמן לנהיגה ניתנים למדידה. ביצענו את הבקשות הבאות:

• בקשה להשלמה אוטומטית (חדשה) של Places API כדי למצוא את טרמינל 5 בנמל התעופה הית'רו
• בקשה ל-Routes API לקבלת מסלול מ-Wembley אל טרמינל 5

הדוגמה הזו היא רק קצה הקרחון של התכונות החדשות של Places API. כדאי לעיין בסוגים החדשים של מקומות, כמו מסלול נחיתה או נמל תעופה בינלאומי.

סיכום

כפי שאפשר לראות, מאמצי הפיתוח הנדרשים כדי לספק שירות פרימיום ללקוחות שמגיעים ברכב הם קטנים יחסית, ואפשר להראות איך אתם מתייחסים לצרכים של הלקוחות.

למטרות פיתוח, תוכלו להשתמש בספריות ובכלים רבים שזמינים כדי לעזור לכם לפתח את השירותים ללקוחות. מומלץ לעיין במאגר GitHub של הפלטפורמה של מפות Google שזמין לכולם.

הפעולות הבאות

תחילת העבודה עם GMP : https://developers.google.com/maps/get-started

הצעות לקריאה נוספת

מסמכי התיעוד של השלמה אוטומטית של Places API (חדש): https://developers.google.com/maps/documentation/places/web-service/place-autocomplete

מסמכי התיעוד של Routes API: https://developers.google.com/maps/documentation/routes

תורמים

המחבר הראשי: Mikko Toivanen | מהנדס פתרונות בפלטפורמה של מפות Google