הטמעת מפה

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

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