הטמעת מפה

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

יצירת כתובת ה-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 בדף האינטרנט, מגדירים את כתובת ה-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.

פרסומות במפה

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

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

פרמטר סוג תיאור ערכים קבילים
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.

ה-API של מפות Google להטמעה מקבל מזהי מקומות של הפרמטרים הבאים של כתובות URL:

  • q
  • origin
  • destination
  • waypoints

כדי להשתמש במזהה מקום, צריך קודם להוסיף את התחילית place_id:. הקוד הבא מציין את העירייה של ניו יורק כמקור הבקשה לקבלת מסלול: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius מגדיר רדיוס שנקבע במטרים, שבו לחפש פנורמה, כשבמרכז קו הרוחב וקו האורך הנתונים. הערכים החוקיים הם מספרים שלמים לא שליליים. ערך ברירת המחדל הוא 50.

  • source מגביל את החיפושים ב-Street View למקורות נבחרים. הערכים החוקיים כוללים:

    • default משתמש במקורות ברירת המחדל ל-Street View. החיפושים אינם מוגבלים למקורות ספציפיים.
    • בoutdoor יש הגבלה על החיפושים לאוספים בחוץ. אוספים פנימיים לא נכללים בתוצאות החיפוש. שימו לב: ייתכן שתמונות פנורמיות בחוץ לא קיימות במיקום שצוין. כמו כן, החיפוש מחזיר תמונות פנורמה רק כאשר ניתן לקבוע אם הן בתוך מבנים או בחוץ. לדוגמה, לא מוחזרים תמונות פנורמיות ב-360° כי לא ידוע אם הן בשטח סגור או בחוץ.