סקירה כללית של ההעברה

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

הפעלת Places API

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

שינויים כלליים

בטבלה הבאה מפורטים כמה מההבדלים העיקריים בין PlacesService לבין Place:

PlacesService (דור קודם) Place (חדש)
כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus, צריך להשתמש ב-method עם קריאה חוזרת. משתמשת ב-Promises ופועלת באופן אסינכרוני.
שיטות דורשות בדיקה של PlacesServiceStatus. אין צורך בבדיקת סטטוס, אפשר להשתמש בטיפול שגיאות רגיל.
שדות של נתוני מיקום מעוצבים לפי פורמט snake case. שדות של נתוני מקומות מוגדרים בפורמט camel case.
מוגבלת לקבוצה קבועה של סוגים של מקומות ושדות של נתוני מקומות. מציעים מבחר מורחב של סוגים של מקומות ושדות של נתוני מקומות שמתעדכנים באופן קבוע.

שינויים ספציפיים ל-API

הכיתה Place מספקת ממשק API לשימוש בספריית Places, ותומכת בדפוסי שימוש מודרניים כמו Promises. בכיתה Place מוצגים אותם שדות נתונים של מקומות וסוגים של מקומות כמו בשירות Places הקודם, והיא כוללת ערכים חדשים רבים לשדות נתונים של מקומות ולסוגים של מקומות.

בטבלה הבאה מוסבר איך המאפיינים של שירות Places ממופים למאפיינים של הכיתה Place:

שירות Places (דור קודם) סיווג מקום (חדש)
שדות של נתוני מקומות שדות נתונים של סיווג מקום
סוגי מקומות סוגי מקומות
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
הכיתה Autocomplete הכיתה PlaceAutocompleteElement
הכיתה SearchBox ---

טעינת ספריית המקומות

האופן שבו האפליקציה טוענת את ספריית Places תלוי במטען האתחול (bootstrap loader) שבו נעשה שימוש. אם האפליקציה משתמשת בייבוא דינמי של ספריות, אפשר לטעון את הספריות הנדרשות בזמן הריצה באמצעות אופרטור await כדי לבצע קריאה ל-importLibrary(), כפי שמוצג כאן:

const { Place } = await google.maps.importLibrary("places");

אם האפליקציה שלכם משתמשת בתג של טעינת סקריפט ישירה, צריך לבקש את הספרייה places בסקריפט הטעינה:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

מידע נוסף על טעינת Maps JavaScript API

בקטע הזה מופיעים המדריכים הבאים שיעזרו לכם להעביר את האפליקציות שלכם ולהשתמש בגרסה העדכנית ביותר של Places API: