הטמעת מפה

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

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

זוהי דוגמה לכתובת URL שטעינה את Maps Embed API:

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

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

מצב directions

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

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

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

פרמטר סוג תיאור ערכים מותרים
origin חובה הגדרת נקודת ההתחלה שממנה יוצגו מסלולים. שם מקום, כתובת, קוד Plus, קואורדינטות של קו רוחב/אורך או מזהה מקום עם קידוד URL. ה-Maps Embed API תומך גם ב-+ וגם ב-%20 כשצריך להימלט ממרווחי טקסט. לדוגמה, ממירים את הכתובת 'City Hall, New York, NY' ל-City+Hall,New+York,NY, או את קודי ה-Plus Code '849VCWC8+R9' ל-849VCWC8%2BR9.
destination חובה מגדיר את נקודת הסיום של המסלול. שם מקום, כתובת, קוד Plus, קואורדינטות של קו רוחב/אורך או מזהה מקום עם קידוד 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

באמצעות Maps Embed API אפשר להציג תמונות Street View כתמונות פנורמיות אינטראקטיביות ממיקומים ייעודיים באזור הכיסוי. אפשר גם לראות תמונות Photosphere שנוספו על ידי משתמשים ואוספים מיוחדים של 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

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

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