הטמעה של מפה

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

יצירת כתובת ה-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="strict-origin-when-cross-origin"
  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="strict-origin-when-cross-origin" מבטיח שהדפדפן ישלח את הדומיין של האתר שלכם בתור הכותרת Referer אל Google. כך ההגבלות על מפתחות ה-API יכולות לאמת את הבקשה, תוך שמירה על הפרטיות של נתיבי הדפים הספציפיים.

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

מידע על הגורם המפנה והגבלות על מפתחות API

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

• strict-origin-when-cross-origin (מומלץ): שליחה של דומיין הבסיס בלבד (למשל, https://example.com/‎) אל Google. כך נתיבי הדפים הספציפיים שלכם נשארים פרטיים, אבל ההגבלות על מפתחות ה-API עדיין פועלות.
• no-referrer-when-downgrade (גרסה קודמת): שליחת כתובת ה-URL המלאה, כולל נתיבי דפים ספציפיים ופרמטרים של שאילתות (למשל, https://example.com/contact?user=123).

מידע נוסף על הכותרת Referrer-Policy

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

אפשר לציין את אחד ממצבי המפה הבאים לשימוש בכתובת ה-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	חובה	מגדיר את המיקום של סמן המפה.	שם המקום, הכתובת, ה-Plus Code או מזהה המקום, עם תווי בריחה (escape) של כתובת URL. ‫Maps Embed API תומך גם ב-+ וגם ב-%20 כשמבצעים בריחה (escape) של רווחים. לדוגמה, המירו את "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 Maps Platform לאזורים נתמכים.

מצב 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 Maps Platform לאזורים נתמכים.

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

מצב streetview

Maps Embed API מאפשר להציג תמונות 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

חובה להשתמש באחד מהפרמטרים הבאים של כתובות 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 Maps Platform לאזורים נתמכים.

מצב 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 Platform לאזורים נתמכים.

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

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