במדריך הזה מוסבר איך להטמיע מפה אינטראקטיבית בדף האינטרנט.
יצירת כתובת ה-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.
פרסומות במפה
ה-Maps Embed API עשוי לכלול פרסום במפה. פורמט המודעה וקבוצת המודעות שמוצגות בכל מפה נתונה עשויים להשתנות ללא הודעה מוקדמת.
בחירת מצבי מפה
אפשר לציין אחד ממצבי המפה הבאים לשימוש בכתובת ה-URL של הבקשה:
place
: הצגת סיכה במפה במקום מסוים או בכתובת מסוימת. כמו ציון דרך, עסק, מקום גיאוגרפי או עיירה.view
: מחזירה מפה ללא סמנים או מסלול הגעה.directions
: הצגת הנתיב בין שתי נקודות או יותר במפה, וגם המרחק וזמן הנסיעה.streetview
: הצגת תצוגות פנורמיות אינטראקטיביות מ: למיקומים ייעודיים.search
: הצגת תוצאות חיפוש במפה המוצגת אזור.
מצב place
כתובת האתר הבאה משתמשת במצב המפה 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 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
¢er=-33.8569,151.2152
&zoom=18
&maptype=satellite
אפשר להשתמש בפרמטרים הבאים:
פרמטר | סוג | תיאור | ערכים מותרים |
---|---|---|---|
center |
חובה | הגדרת מרכז תצוגת המפה. | מקבל ערכים של קווי אורך ורוחב מופרדים בפסיקים; לדוגמה:
37.4218,-122.0840 |
zoom |
אופציונלי | מגדיר את רמת הזום הראשונית של המפה. | הערכים נעים בין 0 (בכל העולם) עד 21
(מבנים נפרדים). הגבול העליון עשוי להשתנות בהתאם לנתוני המפה
זמינה במיקום שנבחר. |
maptype |
אופציונלי | הגדרת סוג המשבצות של המפה לטעינה. | roadmap (ברירת המחדל) או satellite |
language |
אופציונלי | מגדיר את השפה לשימוש ברכיבי ממשק המשתמש ובתצוגה של תוויות במשבצות המפה. כברירת מחדל, המבקרים יראו מפה בשפה שלהם. הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת במערך המשבצות, המערכת תשתמש בשפת ברירת המחדל של מערך המשבצות. | |
region |
אופציונלי | הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. | מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור ב-Unicode ל-ccTLD המוכר ("דומיין ברמה העליונה") בשני תווים. הפלטפורמה של מפות Google פרטי הכיסוי באזורים נתמכים. |
מצב directions
בדוגמה הבאה נעשה שימוש במצב directions
כדי להציג את הנתיב בין Oslow
ו-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' ל-City+Hall,New+York,NY , או את קודי ה-Plus Code '849VCWC8+R9' ל-849VCWC8%2BR9 . |
destination |
חובה | מגדיר את נקודת הסיום של המסלול. | שם מקום, כתובת שמסומנת בתו בריחה (escape) של כתובת 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
ה-API של מפות Google להטמעה מאפשר להציג תמונות 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 לא יוכל למצוא את מזהה הפנורמה.
הפרמטרים הבאים של כתובות 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 |
אופציונלי | הגדרת הגבולות והתוויות המתאימים להצגה, על סמך רגישויות גיאוגרפיות-פוליטיות. | מקבל קוד אזור שצוין כ-2 תווים (לא מספרי) מיפוי של תג משנה של אזור ב-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
מגביל את החיפושים לאוספים של אירועים בחוץ. אוספים בתוך מבנים לא נכללים בתוצאות החיפוש. חשוב לשים לב: תמונות פנורמיות בחוץ אינו קיים במיקום שצוין. כמו כן, חשוב לזכור שבחיפוש בלבד מחזירה תמונות פנורמה שבהן ניתן לקבוע אם הם בתוך מבנים או בחוץ. לדוגמה, תמונות פנורמיות ב-360° לא מוחזרות כי הן לא ידועות בין אם הם בפנים או בחוץ.