איך מפנים משתמשים לפרטי מקומות ומסלולי הגעה במפות Google באמצעות כתובת URL של מפות Google או באמצעות Places API

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

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

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

כתובת ה-URL הזו של מפות Google תקפה לפתיחת מפות Google ולהצגת מיקום על סמך קווי רוחב ואורך. עם זאת, האפליקציה לא מספקת למשתמשים פרטים על מקום ספציפי.

חיפוש רק באמצעות קו רוחב וקו אורך
חיפוש רק באמצעות קו רוחב וקו אורך

קישור חלק של האפליקציה למפות Google באמצעות כתובות URL מדויקות

פתיחת דף פרטי המקום במפות Google
כתובת URL במפות Google עם שם מקום ייחודי מפנה את המשתמשים לדף הפרטים של המקום במפות Google

בפלטפורמה של מפות Google יש שתי שיטות עיקריות ליצירת כתובות URL מדויקות: Places API (חדש), שנדרש לו מפתח API, וכתובות URL של מפות, שהן בחינם ולא נדרש להן מפתח. הפתרונות הבאים מתייחסים לתרחישים שונים ולמקרים שונים של שימוש:

‫GMP Places API(New) מחזיר קבוצה מקיפה של מידע על מקום ספציפי. כשמבקשים את השדה googleMapsUri או googleMapsLinks (על ידי ציון שלו במסכת השדות), תגובת ה-API כוללת אובייקט של מקום. האובייקט הזה מכיל כתובות URL מעוצבות מראש, שאפשר להשתמש בהן כדי לפתוח ישירות את התצוגה המתאימה במפות Google, כמו תצוגת פרטי המקום.

דוגמה:

בקשה לקבלת פרטי מקום

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \
https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE

תגובה של Place Details:

{
    "googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
    "googleMapsLinks": {
        "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
        "placeUri": "https://maps.google.com/?cid=3545450935484072529",
        "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
        "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
        "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
    }
}

‫ChIJ3S-JXmauEmsRUcIaWtf4MzE בדוגמה שלמעלה הוא מזהה המקום של בית האופרה של סידני. מזהה מקום הוא מזהה טקסטואלי שמזהה באופן ייחודי מקום במסד הנתונים של מקומות Google ובמפות Google.

אחזור מזהי מקומות ללא עלות

כדי לאחזר מזהי מקומות באופן פרוגרמטי, אפשר להשתמש בפונקציונליות של Places API: Text Search(ID Only). זוהי שיטה ללא עלות לקבלת מזהי מקומות. מידע נוסף על מזהה מקום ועל בקשה ל-Places API(חדש)

בקשה לחיפוש טקסט ב-Places API(מזהה בלבד):

curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

תגובה של Places API Text Search(מזהה בלבד):

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

אפשר גם לאחזר מזהי מקומות כשמשתמש לוחץ על נקודת עניין במפות Google. מידע נוסף על סמלי נקודות עניין שאפשר ללחוץ עליהם(JavaScript, ‏ Android, ‏ iOS)

הטמעה

כשמשתמשים ב-Places API, מפתחים יכולים פשוט לחלץ את השדה googleMapsUri או googleMapsLinks מהתגובה ולהשתמש בו כדי להפעיל את התצוגה המתאימה באפליקציית מפות Google או בדפדפן אם האפליקציה לא מותקנת.

תכונה תיאור
directionsUri קישור לפתיחת מפות Google כדי להציג מסלול הגעה מהמיקום הנוכחי של המשתמש למקום הזה
placeUri קישור לפתיחת דף הפרטים של המקום הזה במפות Google
writeAReviewUri קישור לפתיחת דף כתיבת הביקורת על המקום הזה במפות Google
reviewsUri קישור לפתיחת דף הביקורות על המקום הזה במפות Google
photosUri קישור לפתיחת דף התמונות של המקום הזה במפות Google

מומלץ לעיין בהדרכה למפתחים ולנסות את התכונה כבר היום.

שימוש בכתובות URL של מפות Google

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

אלה הפעולות שאפשר לבצע במפה:

  • פונקציית החיפוש מפעילה את אפליקציית מפות Google או דפדפן אם האפליקציה לא מותקנת, ומציגה סיכה למיקום ספציפי, או מבצעת חיפוש כללי ומפעילה מפה כדי להציג את התוצאות.

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

  • הפונקציה של פנורמה ב-Street View מאפשרת להפעיל כלי לצפייה בתמונות Street View כפנורמות אינטראקטיביות.

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

במאמר הזה נסביר על שתי פונקציות מרכזיות של כתובות URL במפות:

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

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

הצגת פרטי מקום במפות Google

פונקציית החיפוש מקבלת שני פרמטרים כדי להשלים את החיפוש במקומות: query(חובה) ו-query_place_id(אופציונלי).

חובה לכלול את הפרמטר query בכל בקשות החיפוש. אפשר להזין שם של מקום, קואורדינטות של קו רוחב וקו אורך מופרדות בפסיקים או מונח חיפוש כללי.

המבנה של כתובת ה-URL של החיפוש: 

https://www.google.com/maps/search/?api=1&parameters

תרחיש 1: הצגת פרטי מקום לפי שם מקום ייחודי 

https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
 בדוגמה הזו, צוין רק שם המקום. כתובת ה-URL הזו פותחת את דף הפרטים של בית האופרה של סידני.

פתיחת דף פרטי המקום במפות Google
חיפוש שם של מקום והצגת פרטי המקום

עכשיו נניח שיש מקום עם שם לא ייחודי. מה קורה כשמחפשים רק לפי השם הלא ייחודי הזה? ראו את התרחיש הבא.

תרחיש 2: חיפוש מקומות לפי שם מקום לא ייחודי 

https://www.google.com/maps/search/?api=1&query=7-Eleven

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

פתיחת הדף 'רשימת מקומות' במפות Google
Place list page for searching non-unique name

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

תרחיש 3: הצגת פרטי מקום עם שם לא ייחודי

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

שיטה 1: שימוש בשאילתה מדויקת עם שם מקום וכתובת 

https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia

בכתובת ה-URL הזו, הפרמטר query מפורמט כשם המקום, כתובת. כך אפשר לצמצם את החיפוש ולקשר ישירות למיקום הרצוי.

שיטה 2: שימוש במזהה המקום

מזהה מקום הוא מזהה ייחודי של מקום במסד הנתונים של מקומות Google ובמפות Google. 

https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM

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

תרחיש 4: הצגת פרטי מקום באמצעות קואורדינטות של קו אורך וקו רוחב וגם מזהה המקום

שימוש במזהה המקום מבטיח שבמפות Google יוצגו פרטים על המקום.

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
דף פרטי מקום באמצעות קו רוחב וקו אורך וגם מזהה מקום
דף פרטים של מקום באמצעות קו רוחב וקו אורך וגם מזהה מקום

אחזור מזהי מקומות ללא עלות

כדי לאחזר מזהי מקומות באופן פרוגרמטי, אפשר להשתמש בפונקציונליות של Places API: Text Search(ID Only). זו שיטה ללא עלות לקבלת מזהי מקומות. מידע נוסף על מזהה מקום ועל בקשה של Place API(חדש)

בקשה לחיפוש טקסט ב-Places API(מזהה בלבד): 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

תגובה של Places API Text Search(מזהה בלבד): 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

אפשר גם לאחזר מזהי מקומות כשמשתמש לוחץ על נקודת עניין במפות Google. מידע נוסף על סמלי נקודות עניין שאפשר ללחוץ עליהם(JavaScript, ‏ Android, ‏ iOS)

סיכום

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

  • query=PLACE_NAME, ADDRESS
  • query=PLACE_NAME&query_place_id=PLACE_ID

אם רוצים להציג את הפרטים של מקום ספציפי, לא מומלץ להשתמש רק בקואורדינטות של קו רוחב וקו אורך בפרמטר query. פורמטים כמו query=latitude,longitude,‏ query=PLACE_NAME,latitude,longitude או query=ADDRESS,latitude,longitude לא יובילו באופן עקבי לדף הפרטים של המקום הרצוי. במקום זאת, יוצגו קווי הרוחב והאורך של המיקום.

חיפוש לפי קטגוריה באמצעות כתובות URL של מפות Google

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

תרחיש 1: חיפוש מקומות בסביבה

https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
חיפוש לפי קטגוריה – מקומות בקרבת מקום
חיפוש לפי קטגוריה – מקומות בקרבת מקום

מתן הוראות הגעה באמצעות כתובות URL של מפות Google

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

המבנה של כתובת ה-URL של ההוראות: 

https://www.google.com/maps/dir/?api=1&parameters

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

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

כתובת ה-URL הזו פותחת את מפות Google ומציגה הוראות נסיעה מהמיקום הנוכחי של המשתמש.

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

‫travelmode הוא פרמטר אופציונלי. הוא מגדיר את אמצעי התחבורה. אפשר להגדיר את הפרמטר הזה כך:

  • נסיעה
  • הליכה
  • רכיבה על אופניים
  • רכב דו-גלגלי
  • תחבורה ציבורית

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

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

אחזור מזהי מקומות ללא עלות

כדי לאחזר מזהי מקומות באופן פרוגרמטי, אפשר להשתמש בפונקציונליות של Places API: Text Search(ID Only). זו שיטה ללא עלות לקבלת מזהי מקומות. מידע נוסף על מזהה מקום ועל בקשה של Place API(חדש)

בקשה לחיפוש טקסט ב-Places API(מזהה בלבד): 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

תגובה של Places API Text Search(מזהה בלבד): 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

אפשר גם לאחזר מזהי מקומות כשמשתמש לוחץ על נקודת עניין במפות Google. מידע נוסף על סמלי נקודות עניין שאפשר ללחוץ עליהם(JavaScript, ‏ Android, ‏ iOS)

מסלול מהמיקום הנוכחי של המשתמש
מסלול מהמיקום הנוכחי של המשתמש

תרחיש 3: מתן הוראות ניווט מפורטות

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

הגדרת dir_action=navigate בכתובת ה-URL תפעיל את מפות Google במצב ניווט עם הוראות הגעה מפורטות, אם המיקום הנוכחי של המשתמש(מיקום המכשיר) זמין ומשמש כנקודת המוצא (הוגדר באופן מפורש או נעשה בו שימוש באופן מרומז כשפרמטר נקודת המוצא מושמט). אחרת, תוצג תצוגה מקדימה של המסלול.

הניווט המפורט מופעל כשמגדירים את dir_action=navigate ומתקיימים התנאים הבאים:

  • מיקום המוצא מצוין והוא קרוב למיקום הנוכחי של המשתמש
  • המיקום שממנו הגיעו המשתמשים לא מצוין, והמיקום הנוכחי של המשתמשים זמין

התצוגה המקדימה של המסלול מופעלת כש:

  • dir_action=navigate לא מוגדר
  • הערך dir_action=navigate מוגדר והמוצא מצוין, והמוצא לא קרוב למיקום הנוכחי של המשתמש
  • הערך של dir_action=navigate מוגדר והמקור לא מצוין, והמיקום הנוכחי של המשתמש לא זמין

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

מסלול מפורט תצוגה מקדימה של המסלול
מסלול מפורט
תצוגה מקדימה של המסלול

סיכום

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

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

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

בחירת הגישה הנכונה לאפליקציה

יש שתי אפשרויות עיקריות: שימוש בכתובות URL בפורמט מוגדר מראש שמופיעות ב-Places API, או יצירה ידנית של כתובות URL במפות Google באפליקציה. לכל גישה יש יתרונות וחסרונות משלה.

‫Places API:

  • השדות googleMapsUri ו-googleMapsLinks בתגובה של פרטי המקום מספקים כתובות URL מוכנות לשימוש. כך מקצרים את זמן הפיתוח ומצמצמים את הסיכון לשגיאות בפורמט של כתובות ה-URL.

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

כתובות URL של מפות Google:

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

  • נדרשת הבנה מעמיקה יותר של פרמטרים ומבנה של כתובות URL. אם לא עושים זאת בזהירות, בנייה ידנית מגדילה את הסיכוי לשגיאות.

שיפור כתובות URL במפות Google באמצעות פרמטרים של מנטר התנועה של Urchin

כדי לעזור ל-Google להבין טוב יותר איך מפתחים משלבים כתובות URL של מפות Google, וכדי להבטיח ביצועים אופטימליים, מומלץ לכלול פרמטרים למעקב אחרי מנטר התנועה של Urchin (UTM) כשיוצרים כתובות URL. הוספת הפרמטרים utm_source ו-utm_campaign מאפשרת לכם לספק נתונים חשובים שעוזרים לנו לנתח דפוסי שימוש ולשפר את המוצר 'כתובות URL של מפות Google'.

בפרמטר utm_source, משתמשים בשם של האפליקציה. הפרמטר utm_campaign צריך לשקף את הפעולה שהמשתמש מתכוון לבצע, כמו location_sharing (שיתוף מיקום), place_details_search (חיפוש פרטי מקום) או directions_request (בקשת מסלול).

לדוגמה, כתובת URL עם פרמטרים של מנטר התנועה של Urchin יכולה להיראות כך: 

https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search

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

השלבים הבאים

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

תורמים

מחברים ראשיים:

Teresa Qin | מהנדסת פתרונות לפלטפורמה של מפות Google