הטמעת מפה

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

יצירת כתובת ה-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 בדף האינטרנט שלך, הגדר את כתובת האתר בתור הערך של המאפיין 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.

פרסומות במפה

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

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

אפשר לציין אחד ממצבי המפה הבאים לשימוש בכתובת ה-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	חובה	מגדיר מיקום של סמן במפה.	שם מקום, כתובת, קוד נוסף או מזהה מקום עם תווי בריחה (escape). API של מפות Google להטמעה תומך גם ב-+ וגם ב-%20 בעת בריחה ממרחבים. לדוגמה, אפשר להמיר "בניין עירייה, תל אביב, ישראל" כדי City+Hall,New+York,NY, או קודי OLC "849VCWC8+R9" כדי 849VCWC8%2BR9.
center	אופציונלי	מגדיר את מרכז תצוגת המפה.	מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה: 37.4218,-122.0840
zoom	אופציונלי	מגדיר את רמת הזום הראשונית של המפה.	הערכים נעים בין 0 (בכל העולם) עד 21 (מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה זמינה במיקום שנבחר.
maptype	אופציונלי	מגדיר סוג של אריחי מפה לטעינה.	roadmap (ברירת מחדל) או satellite
language	אופציונלי	מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, למבקרים יראו מפה משלהם בשפת היעד. הפרמטר הזה נתמך רק בחלק ממשבצות המדינות. אם השפה הספציפית המבוקשת לא נתמכת בקבוצת המשבצות. לאחר מכן ייעשה שימוש בשפת ברירת המחדל של קבוצת המשבצות הזו.
region	אופציונלי	הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאו-פוליטיות.	מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור 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, וגם קוד, קו רוחב/קו אורך או מזהה מקום. API של מפות Google להטמעה תומך גם ב-+ וגם ב-%20 בעת בריחה ממרחבים. לדוגמה, אפשר להמיר "בניין עירייה, תל אביב, ישראל" כדי City+Hall,New+York,NY, או קודי OLC "849VCWC8+R9" כדי 849VCWC8%2BR9.
destination	חובה	מגדיר את נקודת הסיום של המסלול.	שם של מקום, כתובת שמסומנת בתו בריחה (escape) של כתובת URL, וגם קוד, קו רוחב/קו אורך או מזהה מקום. API של מפות Google להטמעה תומך גם ב-+ וגם ב-%20 בעת בריחה ממרחבים. לדוגמה, אפשר להמיר "בניין עירייה, תל אביב, ישראל" כדי City+Hall,New+York,NY, או קודי OLC "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	אופציונלי	הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאו-פוליטיות.	מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור unicode ל-ccTLD מוכר ("דומיין ברמה עליונה") בשני תווים. הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים.

מצב streetview

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

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

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