הטמעת מפה

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

יצירת כתובת ה-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. ה-API של מפות Google להטמעה תומך גם ב-+ וגם ב-%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.

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

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