הטמעה של מפה

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

יצירת כתובת 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.

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

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