דף זה תורגם על ידי Cloud Translation API.

איך מפנים משתמשים לפרטי מקומות ומסלולי הגעה במפות 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 מדויקות

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

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

שימוש בשדה googleMapsUri או בשדה googleMapsLinks של GMP Places API(חדש)

GMP Places API‏(חדש) מחזיר קבוצה מקיפה של מידע על מקום ספציפי. כשמבקשים את השדה 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). זוהי שיטה ללא עלות לקבלת מזהי מקומות. מידע נוסף על מזהה מקום ועל הבקשה 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‏(מזהה בלבד):

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

אפשר לאחזר מזהי מקומות גם כשמשתמש לוחץ או מקשיב על נקודת עניין במפות. מידע נוסף על סמלי נקודות עניין שניתן ללחוץ עליהם(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 זהה ללא קשר לפלטפורמה שבה אתם משתמשים. אין צורך במפתח API של Google כדי להשתמש בכתובות URL של מפות Google.

הפעולות הזמינות במפה הן:

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

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

כאן נרחיב על שתי פונקציות עיקריות של כתובות 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 הזו פותחת את דף הפרטים של בית האופרה של סידני.

חיפוש שם מקום והצגת פרטי המקום

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

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

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

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

דף רשימת המקומות לחיפוש שם לא ייחודי

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

תרחיש 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‏(מזהה בלבד):

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

אפשר לאחזר מזהי מקומות גם כשמשתמש לוחץ או מקשיב על נקודת עניין במפות. מידע נוסף על סמלי נקודות עניין שניתן ללחוץ עליהן(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 להנחיות מפורטות הוראות ליצירת כתובות 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 הוא אופציונלי. הוא מגדיר את אופן הנסיעה. אפשר להגדיר את הפרמטר הזה כ:

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

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

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

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

בקשה לחיפוש טקסט ב-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‏(מזהה בלבד):

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

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

תרחיש 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 בבניית כתובת ה-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