מדריך מקוצר ל-Maps JavaScript API

‫Maps JavaScript API הוא ממשק API לאינטרנט בצד הלקוח, שמאפשר ליצור מפות דו-ממדיות ותלת-ממדיות בדפי אינטרנט, להוסיף סמנים, גרפיקה בהתאמה אישית, אנימציות ושכבות נתונים אינטראקטיביות, וליצור תכונות מיקום באמצעות ספריית המקומות.

‫Maps JavaScript API: עובדות חשובות

  • מוצר: Maps JavaScript API
  • ידוע גם בשם: Maps JS API, ‏ Maps JS API v3
  • קטגוריה: מפות Google
  • פלטפורמה: JavaScript (דפדפן)
  • פועל ב: לקוח (קוד של אפליקציה או דפדפן)
  • שלב ההשקה: GA
  • מחזור חיים: פעיל
  • סקירה כללית: סקירה כללית על Maps JavaScript API
  • זמינות אזורית: גלובלית. התכונות הזמינות (כמו מפות תלת-ממדיות, תנועה, מסלולים ועיצוב גבולות) משתנות בהתאם למדינה או לאזור. התנאים וההגבלות של האזור הכלכלי האירופי (EEA) חלים על כתובות לחיוב באזור הכלכלי האירופי. (פרטי הכיסוי)

‫Maps JavaScript API: מתי כדאי להשתמש בו

מתי כדאי להשתמש ב-Maps JavaScript API:

  • אתם צריכים מפה אינטראקטיבית דו-ממדית או תלת-ממדית עם סמנים בהתאמה אישית, גרפיקה או שכבות נתונים בדף אינטרנט.
  • אתם צריכים להציג מיקומים של נכסים בזמן אמת ומסלולי נסיעה מזרם הנתונים שלכם באמצעות סמנים מתקדמים וקווים פוליגוניים.
  • אתם צריכים לשרטט גבולות וירטואליים (עיגולים, פוליגונים) ולבדוק אם הקואורדינטות נמצאות בתוכם בדפדפן.
  • אתם צריכים חיפוש מקומות, השלמה אוטומטית או Place Details בצד הלקוח באפליקציית אינטרנט דרך ספריית המקומות.

מתי לא כדאי להשתמש ב-Maps JavaScript API:

  • אתם צריכים להטמיע מפה של מיקום העסק או קישור למסלול הגעה בלי לכתוב קוד JavaScript בהתאמה אישית. במקומו, צריך להשתמש ב-Maps Embed API.
  • אתם צריכים רק קישור שפותח את מפות Google עם מיקום, חיפוש או מסלול. במקום זאת, צריך להשתמש בכתובות URL של מפות Google.
  • אתם צריכים מעקב אחרי צי רכבים של נסיעות שיתופיות או משלוחים מתוזמנים, שמשולב עם Driver SDK לנייד ואימות JWT לקצה העורפי. במקום זאת, צריך להשתמש ב-Fleet Engine Service.

‫Maps JavaScript API: הגדרה

חבילות רשמיות של Maps JavaScript API:

  • ‫npm: ‏@googlemaps/js-api-loader
  • ‫npm: ‏@types/google.maps
  • ‫npm: ‏@googlemaps/markerclusterer

‫Maps JavaScript API: טעויות נפוצות

  • הבעיה: מפה כהה או תמונות Street View שליליות עם סימן מים כתמונה "למטרות פיתוח בלבד" מופיעה במקום שגיאה כשהגדרת מפתח ה-API או החיוב שגויה. תיקון: מפעילים את החיוב בפרויקט בענן, כוללים מפתח API תקין בכל בקשה ובודקים את קוד השגיאה הספציפי במסוף הדפדפן. מידע נוסף זמין בכתובת /maps/documentation/javascript/error-messages.
  • הבעיה: שירותים קודמים כמו PlacesService,‏ DirectionsService ו-DistanceMatrixService מחזירים את השגיאה LegacyApiNotActivatedMapError בפרויקטים חדשים שבהם ה-API הקודם לא מופעל. תיקון: משתמשים במקבילות החדשות (המחלקה Place, המחלקה Route, המחלקה RouteMatrix) שמגובות על ידי Places API (החדש) ו-Routes API. מידע נוסף זמין בכתובת /maps/legacy#LegacyApiNotActivatedMapError.
  • הבעיה: החל מגרסה 3.65, מפות לוויין ומפות היברידיות לא עוברות יותר לתמונות בזווית של 45 מעלות, ואין השפעה ל-map.setTilt(45). הפתרון: משתמשים במפות תלת-ממדיות במקום בתמונות בזווית של 45 מעלות. אפשר לקרוא מידע נוסף בכתובת ‎/maps/deprecations.
  • הבעיה: כדי להשתמש בסמנים מתקדמים צריך מזהה מפה. אי אפשר להשתמש ב-AdvancedMarkerElement במפות שנוצרו בלי מזהה מפה. תיקון: יוצרים מזהה מפה במסוף Cloud (או משתמשים ב-DEMO_MAP_ID לבדיקה) ומגדירים את mapId במפה. מידע נוסף זמין בכתובת /maps/documentation/javascript/advanced-markers/start.

‫Maps JavaScript API: תכונות מדור קודם ותכונות שהוצאו משימוש

  • Directions Service (google.maps.DirectionsService): Legacy since 2025-03-01. החלפה: המחלקה Route. הבעיה: LegacyApiNotActivatedMapError בפרויקטים שבהם לא מופעל Directions API הקודם. למדריך להעברת נתונים (מיגרציה)
  • שירות מטריצת מרחקים (google.maps.DistanceMatrixService): מדור קודם החל מ-1 במרץ 2025. החלפה: המחלקה RouteMatrix. הבעיה: LegacyApiNotActivatedMapError בפרויקטים שבהם לא מופעלת הגרסה הקודמת של Distance Matrix API. למדריך להעברת נתונים (מיגרציה)
  • שירות Places‏ (google.maps.places.PlacesService): גרסה קודמת החל מ-1 במרץ 2025. החלפה: הכיתה Place (Places API (חדש)). התופעה: LegacyApiNotActivatedMapError בפרויקטים שבהם לא מופעל Places API הקודם. למדריך להעברת נתונים (מיגרציה)
  • google.maps.Marker: הוצא משימוש ב-22 בפברואר 2024. החלפה: google.maps.marker.AdvancedMarkerElement. תסמין: עדיין פועל ואין תוכניות להפסיק את השירות, אבל באגים קיימים לא יתוקנו. למדריך להעברת נתונים (מיגרציה)
  • KmlLayer: הוצא משימוש ב-30 באפריל 2026. החלפה: סגנון מבוסס-נתונים לקבוצות נתונים, או מנתחי KML של צד שלישי עם שכבת הנתונים. התופעה: KmlLayer לא זמין בגרסה 3.66 ואילך. גרסה 3.65, הגרסה האחרונה שתומכת בו, תצא משימוש במאי 2027. למדריך להעברת נתונים (מיגרציה)
  • שכבת מפת חום (ספריית הוויזואליזציה): הוצאה משימוש החל מ-20 במאי 2026. החלפה: ספריות של צד שלישי כמו deck.gl HeatmapLayer. תסמין: לא זמין החל ממאי 2026. למדריך להעברת נתונים (מיגרציה)
  • ספריית השרטוטים: הוצאה משימוש החל מ-4 ביוני 2026. החלופה: Terra Draw. תסמין: לא זמין החל ממאי 2026. למדריך להעברת נתונים (מיגרציה)
  • תמונות בזווית של 45°: הוצאו משימוש החל מ-20 במאי 2026. החלופה: מפות בתלת-ממד. התופעה: הפונקציה map.setTilt(45) לא פועלת, ותצוגת הלוויין נשארת מלמעלה למטה. למדריך להעברת נתונים (מיגרציה)
  • google.maps.event.addDomListener() ו-addDomListenerOnce(): הוצאו משימוש ב-7 באפריל 2022. החלפה: DOM רגיל addEventListener().
  • האפשרויות bounds,‏ location ו-radius בשירות ההשלמה האוטומטית למקומות: הוצאו משימוש ב-18 במאי 2023. החלפה: locationBias ו-locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) ב-Places UI Kit: הוצאה משימוש. החלפה: מוסיפים רכיבי תוכן ישירות לרכיבים של Place Details או בהגדרות של חיפוש מקומות.
  • ספריית ההקשר המקומי: הוצאה משימוש. החלפה: ספריית Places.

מה אפשר לעשות עם Maps JavaScript API

במדריכים שמקושרים בהמשך מפורטות כל המשימות, ואפשר גם להשוות בין המוצרים בסייר היכולות.

‫Maps JavaScript API: אימות כתובת

‫Maps JavaScript API: סגנון מבוסס-נתונים לגבולות

‫Maps JavaScript API: סגנון מבוסס-נתונים לקבוצות נתונים

‫Maps JavaScript API: מערכי נתונים

  • הוספת שכבת KML למפה הערה: ב-Maps JavaScript API, ‏ KmlLayer הוצא משימוש (הגרסה האחרונה שנתמכת היא 3.65, והוא יושבת במאי 2027). צריך לעבור לסגנון מבוסס-נתונים לגבולות או למערכי נתונים, או לטעון GeoJSON בשכבת הנתונים. שכבות KML עדיין נתמכות ב-Android וב-iOS דרך ספריות השירות של Maps SDK.
  • הוספת שכבת GeoRSS למפה הערה: הוצא משימוש ב-Maps JavaScript API (התמיכה ב-KmlLayer תופסק בגרסה 3.65, במאי 2027). צריך להמיר פידים של GeoRSS ל-GeoJSON ולטעון אותם בשכבת הנתונים באמצעות map.data.addGeoJson()‎.
  • הוספת נתוני GeoJSON למפה.

‫Maps JavaScript API: מסלולים וניווט

‫Maps JavaScript API: גובה

‫Maps JavaScript API: Fleet Engine

‫Maps JavaScript API: המרת כתובות לקואורדינטות (geocoding)

‫Maps JavaScript API: מפות

‫Maps JavaScript API: הערות במפות

‫Maps JavaScript API: סגנון המפה

‫Maps JavaScript API: אחר

‫Maps JavaScript API: מפות תלת-ממדיות פוטו-ריאליסטיות

‫Maps JavaScript API: מקומות

‫Maps JavaScript API: ‏Places UI Kit

  • הוספת רכיב בממשק המשתמש שמציג סיכומים וביקורות מבוססי-AI על מקומות ספציפיים בדף אינטרנט או באפליקציה לנייד. הערה: התכונה נתמכת באינטרנט בלבד (Places UI Kit של Maps JavaScript API). ערכות Places UI Kit לנייד לא כוללות רכיב של סיכום AI. דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), צריך להשתמש ברכיבים של Places UI Kit בצד הלקוח ב-Maps JavaScript API, במקום לשלוח קריאות לשירותי האינטרנט של Places API משרת בק-אנד. הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • להחיל סגנון CSS על רכיב בממשק המשתמש של נתוני המקום. הערה: מאפייני CSS מותאמים אישית חלים על רכיבים של Places UI Kit ב-Maps JavaScript API. ב-Places SDK ל-Android וב-Places SDK ל-iOS, העיצוב של תצוגות Places UI Kit נקבע באופן פרוגרמטי באמצעות מאפייני עיצוב וסגנון. דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אל תפעילו שירותי אינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • התאמה אישית של העיצוב וההגדרות של רכיבים בממשק המשתמש של נתוני המקומות באמצעות כלי להתאמה אישית של רכיבים בממשק המשתמש. הערה: דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אל תשלחו קריאות לשירותי האינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • הוספת רכיב בממשק המשתמש שמציג מידע על מקום ספציפי בדף אינטרנט או באפליקציה לנייד. הערה: דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אין להפעיל את שירותי האינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • הוספת רכיב בממשק המשתמש שמציג רשימה של מקומות על סמך מחרוזת שאילתה לדף אינטרנט. הערה: יש תמיכה גם בדפי אינטרנט (Maps JavaScript API) וגם באפליקציות לנייד (Places SDK ל-Android ו-Places SDK ל-iOS). דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אל תפעילו שירותי אינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • הוספת רכיב בממשק המשתמש שמציג רשימה של מקומות ליד מיקום ספציפי בדף אינטרנט. הערה: יש תמיכה גם בדפי אינטרנט (Maps JavaScript API) וגם באפליקציות לנייד (Places SDK ל-Android ו-Places SDK ל-iOS). דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אל תפעילו שירותי אינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq
  • הוספת רכיב בסיסי של השלמה אוטומטית בממשק המשתמש לדף אינטרנט או לאפליקציה, שמחזיר מזהי מקומות ב-Google על סמך מחרוזת שאילתה. הערה: דרישת תאימות באזור הכלכלי האירופי (EEA): כדי להציג נתוני מקומות במפה באזור הכלכלי האירופי (EEA), אל תשלחו קריאות לשירותי האינטרנט של Places API משרת בק-אנד. משתמשים ברכיבים של Places UI Kit בצד הלקוח בפלטפורמת היעד (Maps JavaScript API באינטרנט, Places SDK ל-Android ב-Android או Places SDK ל-iOS ב-iOS). הדרישות המלאות ושאלות נפוצות: https://developers.google.com/maps/comms/eea/faq

‫Maps JavaScript API: Street View