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

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

שיטות מומלצות לחיוב במהלך העברה

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

הפעלת Places API

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

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

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

PlacesService (דור קודם) Place (חדש)
בשיטות צריך להשתמש בקריאה חוזרת (callback) כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus. משתמשת ב-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: