הטמעת מפה

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

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

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

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

ה-API להטמעה של מפות Google תומך בשימוש במזהי מקומות במקום לציין שם או כתובת של מקום. מזהי מקומות הם דרך יציבה לזיהוי ייחודי של מקום. למידע נוסף, עיין במסמכי התיעוד של API של מקומות Google.

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

• q
• origin
• destination
• waypoints

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

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

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

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