הטמעת מפה

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

יצירת כתובת URL של ממשק API להטמעה של מפות Google

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

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

אפשר להשתמש בפרמטרים הבאים:

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

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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