הטמעת מפה

במדריך הזה מוסבר איך להטמיע מפה אינטראקטיבית בדף האינטרנט.

יצירת כתובת ה-URL של Maps Embed API

לפניכם כתובת URL לדוגמה שטוענת את ממשק ה-API של מפות Google להטמעה:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

מחליפים את:

  • MAP_MODE עם מצב המפה.
  • YOUR_API_KEY במפתח ה-API שלכם. מידע נוסף זמין במאמר קבלת מפתח API.
  • PARAMETERS בפרמטרים הנדרשים והאופציונליים של המפה במצב תצוגה.

הוספת כתובת ה-URL ל-iframe

כדי להשתמש ב-Maps Embed API בדף האינטרנט, מגדירים את כתובת ה-URL שיצרתם כערך של המאפיין src של iframe. אתם יכולים לשלוט בגודל המפה באמצעות height ו-width של ה-iframe, לדוגמה:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

דוגמת ה-iframe שלמעלה משתמשת במאפיינים הנוספים:

  • המאפיין allowfullscreen מאפשר להציג חלקים מסוימים במפה במסך מלא.
  • המאפיינים frameborder="0" ו-style="border:0" להסרה של נכסי ברירת המחדל גבול של iframe מסביב למפה.
  • המאפיין referrerpolicy="no-referrer-when-downgrade" כדי לאפשר את הדפדפן ישלח את כתובת ה-URL המלאה ככותרת Referer עם הבקשה, כך ההגבלות על מפתחות API עשויות לפעול באופן תקין.

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

הגבלות על מפתחות API

אם באתר המארח יש מטא תג referrer שמוגדר כ-no-referrer או כ-same-origin, הדפדפן לא ישלח את הכותרת Referer אל Google. הזה עלול לגרום להגבלה על מפתחות API. כדי לדחות את הבקשות. כדי שההגבלה תפעל בצורה תקינה, צריך להוסיף referrerpolicy ל-iframe, כמו בדוגמה שלמעלה, כדי באופן מפורש מאפשרת שליחה של כותרות Referer ל-Google.

פרסומות במפה

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

בחירת מצבי מפה

אפשר לציין אחד ממצבי המפה הבאים לשימוש בכתובת ה-URL של הבקשה:

  • place: הצגת סיכה במפה במקום מסוים או בכתובת מסוימת. כמו ציון דרך, עסק, מקום גיאוגרפי או עיירה.
  • view: מחזירה מפה ללא סמנים או מסלול הגעה.
  • directions: הצגת הנתיב בין שתי נקודות או יותר במפה, וגם המרחק וזמן הנסיעה.
  • streetview: הצגת תצוגות פנורמיות אינטראקטיביות מ: למיקומים ייעודיים.
  • search: הצגת תוצאות חיפוש במפה המוצגת אזור.

מצב place

כתובת האתר הבאה משתמשת במצב המפה place כדי להציג סמן מפה מגדל אייפל:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

אפשר להשתמש בפרמטרים הבאים:

פרמטר סוג תיאור ערכים מותרים
q חובה מגדיר מיקום של סמן במפה. שם מקום, כתובת, קוד OLC או מזהה מקום עם תווי בריחה בכתובת URL. ה-Maps Embed API תומך גם ב-+ וגם ב-%20 כשצריך להימלט ממרווחי טקסט. לדוגמה, ממירים את הכתובת 'City Hall, New York, NY' ל-City+Hall,New+York,NY, או את קודי ה-Plus Code '849VCWC8+R9' ל-849VCWC8%2BR9.
center אופציונלי הגדרת מרכז תצוגת המפה. מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom אופציונלי מגדיר את רמת הזום הראשונית של המפה. הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype אופציונלי הגדרת סוג המשבצות של המפה לטעינה. roadmap (ברירת המחדל) או satellite
language אופציונלי מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות.
region אופציונלי הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. הפרמטר מקבל קוד אזור שצוין בתג משנה של אזור ב-Unicode בן שני תווים (לא מספריים) שממופה לערכים של שני תווים של ccTLD מוכרים ('דומיין ברמה עליונה'). הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים.

מצב view

בדוגמה הבאה נעשה שימוש במצב view ובפרמטר האופציונלי maptype כדי להציג תצוגת לוויין של המפה:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

אפשר להשתמש בפרמטרים הבאים:

פרמטר סוג תיאור ערכים מותרים
center חובה הגדרת מרכז תצוגת המפה. מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom אופציונלי מגדיר את רמת הזום הראשונית של המפה. הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype אופציונלי הגדרת סוג המשבצות של המפה לטעינה. roadmap (ברירת המחדל) או satellite
language אופציונלי מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות.
region אופציונלי הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור ב-Unicode ל-ccTLD המוכר ("דומיין ברמה העליונה") בשני תווים. הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים.

מצב directions

בדוגמה הבאה נעשה שימוש במצב directions כדי להציג את הנתיב בין Oslow ו-Telemark, נורווגיה, המרחק וזמן ההגעה להימנע מכבישי אגרה ומכבישים מהירים.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

אפשר להשתמש בפרמטרים הבאים:

פרמטר סוג תיאור ערכים מותרים
origin חובה הגדרת נקודת ההתחלה שממנה יוצג מסלול. שם מקום, כתובת שמסומנת בתו בריחה (escape) של כתובת URL, וגם קוד, קו רוחב/קו אורך או מזהה מקום. ה-Maps Embed API תומך גם ב-+ וגם ב-%20 כשצריך להימלט ממרווחי טקסט. לדוגמה, ממירים את הכתובת 'City Hall, New York, NY' ל-City+Hall,New+York,NY, או את קודי ה-Plus Code '849VCWC8+R9' ל-849VCWC8%2BR9.
destination חובה מגדיר את נקודת הסיום של המסלול. שם מקום, כתובת שמסומנת בתו בריחה (escape) של כתובת URL, וגם קוד, קו רוחב/קו אורך או מזהה מקום. ה-Maps Embed API תומך גם ב-+ וגם ב-%20 כשצריך להימלט ממרווחי טקסט. לדוגמה, ממירים את הכתובת 'City Hall, New York, NY' ל-City+Hall,New+York,NY, או את קודי ה-Plus Code '849VCWC8+R9' ל-849VCWC8%2BR9.
waypoints אופציונלי מציינים מקום ביניים אחד או יותר כדי לתכנן מסלול בין המקור ליעד. שם המקום, הכתובת או מזהה המקום. אפשר לציין כמה נקודות דרך באמצעות קו אנכי (|) כדי להפריד בין המקומות (למשל Berlin,Germany|Paris,France). אפשר לציין עד 20 נקודות דרך.
mode אופציונלי הגדרת אופן הנסיעה. אם לא צוין מצב, ב-Maps Embed API יוצג אחד או יותר מהמצבים הרלוונטיים ביותר למסלול שצוין. driving, walking (מעדיפה להולכי רגל שבילים ומדרכות, היכן שהדבר זמין), bicycling (שאותם מסלולים דרך שבילי אופניים ורחובות מועדפים, אם יש כאלה), transit או flying.
avoid אופציונלי מציין את התכונות שיש להימנע מהן במסלולים. חשוב לזכור שהפעולה הזו לא מונעת מסלולים שכוללים את התכונות המוגבלות, אלא גורמת לכך שהתוצאה תהיה מסלולים נוחים יותר. tolls, ferries ו/או highways. מפרידים בין כמה ערכים באמצעות קו אנכי (למשל avoid=tolls|highways).
units אופציונלי מציינת את שיטת המדידה, המדד או השיטה האימפריאלית כשמציגים את המרחקים בתוצאות. אם לא מציינים את units, המדינה origin של השאילתה קובעת באילו יחידות יש להשתמש. metric או imperial
center אופציונלי הגדרת מרכז תצוגת המפה. מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom אופציונלי מגדיר את רמת הזום הראשונית של המפה. הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype אופציונלי הגדרת סוג המשבצות של המפה לטעינה. roadmap (ברירת המחדל) או satellite
language אופציונלי מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות.
region אופציונלי הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. הפרמטר מקבל קוד אזור שצוין בתג משנה של אזור ב-Unicode בן שני תווים (לא מספריים) שממופה לערכים של שני תווים של ccTLD מוכרים ('דומיין ברמה עליונה'). הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים.

מצב streetview

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

כל תמונה פנורמית ב-Street View מספקת תמונה מלאה של 360 מעלות המיקום. התמונות מכילות 360 מעלות של תצוגה אופקית ו-180 מעלות של תצוגה אנכית (ישירה למעלה עד למטה). מצב streetview מספק מציג שמעבד את התוצאה פנורמית כספרה עם מצלמה במרכזה. אפשר לבצע פעולות במצלמה כדי לשלוט בזום ובכיוון של המצלמה.

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

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

אחד מהפרמטרים הבאים של כתובת האתר הוא חובה:

  • הפונקציה location מקבלת קווי אורך ורוחב כערכים מופרדים בפסיקים ערכים (46.414382,10.013988). ממשק ה-API יציג את הפנורמה שהצילום שלו הוא הכי קרוב למיקום הזה. התמונות ב-Street View מתעדכנות מדי פעם, ויכול להיות שהתמונות צולמו מזוויות שונות במקצת בכל פעם. לכן, יכול להיות שהמיקום שלכם יוצג בתמונה פנורמית שונה כשהתמונות יתעדכנו.

  • pano הוא מזהה פנורמה ספציפי. אם תציינו pano אפשר גם לציין location. המערכת תשתמש ב-location רק אם ה-API לא יוכל למצוא את מזהה הפנורמה.

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

פרמטר סוג תיאור ערכים מותרים
heading אופציונלי מציין את כיוון המצפן של המצלמה במעלות בכיוון השעון ממזרח. ערך במעלות, מ-180° ל-360°
pitch אופציונלי מציין את הזווית, למעלה או למטה, של המצלמה. ערכים חיוביים יגרמו להטיית המצלמה כלפי מעלה, וערכים שליליים יגרמו להטיית המצלמה כלפי מטה. גובה ברירת המחדל של 0° נקבע על סמך מיקום המצלמה, כאשר התמונה צולמה. לכן, זווית נטייה של 0° היא לרוב, אבל לא תמיד, אופקי. לדוגמה, תמונה שצולמה על גבעה תהיה בדרך כלל בזווית ברירת מחדל שאינה אופקית. הערך במעלות מ-90°- עד 90°
fov אופציונלי קובע את שדה הראייה האופקי של התמונה. הערך שמוגדר כברירת מחדל הוא 90°. כשעובדים עם חלון תצוגה בגודל קבוע, שדה התצוגה יכול להיחשב כרמת הזום, כאשר מספרים קטנים יותר מציינים רמת זום גבוהה יותר. ערך במעלות, בטווח של 10° עד 100°
center אופציונלי הגדרת מרכז תצוגת המפה. מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom אופציונלי מגדיר את רמת הזום הראשונית של המפה. הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype אופציונלי הגדרת סוג המשבצות של המפה לטעינה. roadmap (ברירת המחדל) או satellite
language אופציונלי מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות.
region אופציונלי הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. הפרמטר מקבל קוד אזור שצוין בתג משנה של אזור ב-Unicode בן שני תווים (לא מספריים) שממופה לערכים של שני תווים של ccTLD מוכרים ('דומיין ברמה עליונה'). הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים.

מצב search

במצב Search מוצגות תוצאות חיפוש באזור המפה הגלוי. מומלץ להגדיר מיקום לחיפוש, על ידי הכללת מיקום במונח החיפוש (record+stores+in+Seattle) או על ידי הכללת הפרמטרים center ו-zoom כדי להגביל את החיפוש.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

אפשר להשתמש בפרמטרים הבאים:

פרמטר סוג תיאור ערכים מותרים
q חובה מגדיר את מונח החיפוש. הוא יכול לכלול הגבלה גיאוגרפית, כמו in+Seattle או near+98033.
center אופציונלי הגדרת מרכז תצוגת המפה. מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom אופציונלי מגדיר את רמת הזום הראשונית של המפה. הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype אופציונלי הגדרת סוג המשבצות של המפה לטעינה. roadmap (ברירת המחדל) או satellite
language אופציונלי מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות.
region אופציונלי הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור ב-Unicode ל-ccTLD המוכר ("דומיין ברמה העליונה") בשני תווים. כאן אפשר למצוא את רשימת האזורים הנתמכים בפלטפורמה של מפות Google.

פרמטרים של מזהה מקום

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

Maps Embed API מקבל מזהי מקומות עבור כתובת ה-URL הבאה :

  • q
  • origin
  • destination
  • waypoints

כדי להשתמש במזהה מקום, קודם צריך להוסיף את התחילית place_id:. הקוד הבא מציין את בניין העירייה של ניו יורק בתור המקור של מסלול נסיעה בקשה: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

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

  • source מגביל את החיפושים ב-Street View למקורות נבחרים. הערכים החוקיים כוללים:

    • default משתמש במקורות ברירת המחדל של Street View. החיפושים לא מוגבלים למקורות ספציפיים.
    • outdoor מגביל את החיפושים לאוספים של אירועים בחוץ. אוספים בתוך מבנים לא נכללים בתוצאות החיפוש. חשוב לשים לב: תמונות פנורמיות בחוץ אינו קיים במיקום שצוין. כמו כן, חשוב לזכור שבחיפוש בלבד מחזירה תמונות פנורמה שבהן ניתן לקבוע אם הם בתוך מבנים או בחוץ. לדוגמה, תמונות פנורמיות ב-360° לא מוחזרות כי הן לא ידועות בין אם הם בפנים או בחוץ.