השלמה אוטומטית (חדשה) מחזירה חיזויים של מקומות בתגובה לבקשה שכוללת מחרוזת חיפוש טקסט וגבולות גיאוגרפיים ששולטים באזור החיפוש. ההשלמה האוטומטית יכולה להתאים למילים מלאות ולמחרוזות משנה של הקלט, ולפתור שמות של מקומות, כתובות וקודי Plus Code. האפליקציה יכולה לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק תחזיות של מקומות ושאילתות תוך כדי הקלדה.
לדוגמה, אתם קוראים להשלמה האוטומטית באמצעות מחרוזת שמכילה קלט חלקי של משתמש, "Sicilian piz", ואזור החיפוש מוגבל לסן פרנסיסקו, קליפורניה. התגובה תכיל רשימה של הצעות למקומות שתואמים למחרוזת החיפוש ולאזור החיפוש, כמו המסעדה "Sicilian Pizza Kitchen". התחזיות שמוחזרות לגבי המקומות מיועדות להצגה למשתמש כדי לעזור לו לבחור את המקום הרצוי. אתם יכולים לשלוח בקשה מסוג Place Details (New) כדי לקבל מידע נוסף על כל אחד מהמקומות שמוחזרים בתחזיות.
יש שתי דרכים עיקריות לשלב את הפונקציונליות של ההשלמה האוטומטית (חדש) באפליקציה:
- הוספת הווידג'ט "השלמה אוטומטית למקומות": מספק חוויית השלמה אוטומטית של חיפוש שמוכנה לשימוש באמצעות המחלקה
PlaceAutocomplete, שמציגה חיזויים בזמן שהמשתמש מקליד. - קבלת חיזויים של מקומות באופן פרוגרמטי: שולחים קריאה ישירות ל-API כדי לאחזר חיזויים ולהציג אותם בממשק משתמש מותאם אישית.
הוספת הווידג'ט השלמה אוטומטית למקומות
כדי לספק חוויה עקבית של השלמה אוטומטית למקומות בצורה קלה יותר, אפשר להוסיף את הווידג'ט Place Autocomplete לאפליקציה. הווידג'ט מספק ממשק ייעודי במסך מלא שמטפל בקלט של משתמשים ומציג לו הצעות להשלמת החיפוש של מקומות, וגם מחזיר לאפליקציה אובייקטים מסוג AutocompletePrediction. לאחר מכן אפשר לשלוח בקשה מסוג Place Details (חדש) כדי לקבל מידע נוסף על כל אחת מהצעות להשלמת החיפוש של המקומות.
כמו בקבלת חיזויים של מקומות באופן פרוגרמטי, הווידג'ט "השלמה אוטומטית למקומות" מאפשר להשתמש בטוקנים לסשנים כדי לקבץ בקשות של השלמה אוטומטית לסשן לצורכי חיוב. אפשר להעביר טוקן לסשן כשיוצרים את ה-Intent של הווידג'ט על ידי קריאה ל-setAutocompleteSessionToken(). אם לא תספקו טוקן לסשן, הווידג'ט ייצור אחד בשבילכם, ותוכלו לגשת אליו באמצעות קריאה ל-getSessionTokenFromIntent(). מידע נוסף על השימוש בטוקנים לסשנים זמין במאמר מידע על טוקנים לסשנים.
כדי להוסיף את הווידג'ט 'השלמה אוטומטית למקומות' לאפליקציה:
(אופציונלי) מגדירים טוקן לסשן. אם לא תספקו טוקן לסשן, הווידג'ט ייצור אחד בשבילכם.
מגדירים
autocompleteIntentעם הפרמטרים הרצויים ועם טוקן הסשן.הגדרת
ActivityResultLauncherל-StartActivityForResult. ה-launcher הזה יטפל בתוצאה שמוחזרת מהפעילות של ההשלמה האוטומטית.מטפלים בתוצאה בקריאה החוזרת (callback) של
ActivityResultLauncher. התהליך הזה כולל חילוץ שלAutocompletePredictionו-AutocompleteSessionToken(אם לא סיפקתם אותם בעצמכם), טיפול בשגיאות ואפשרות לשלוח בקשתfetchPlace()כדי לקבל פרטים נוספים על מקום.מפעילים את הכוונה באמצעות
placeAutocompleteActivityResultLauncher
הדוגמאות הבאות מדגימות איך להוסיף את הווידג'ט השלמה אוטומטית למקומות באמצעות Kotlin ו-Java:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
התאמה אישית של העיצוב
כשיוצרים מופע של חוויית השלמה אוטומטית, אפשר לציין עיצוב שמחליף את כל מאפייני הסגנון שמוגדרים כברירת מחדל. אתם יכולים להתאים אישית את הצבעים, הטיפוגרפיה, הריווח, הגבולות והפינות של רכיב ההשלמה האוטומטית למקומות. ערך ברירת המחדל הוא PlacesMaterialTheme. כל מאפייני העיצוב שלא מוגדרים מחדש משתמשים בסגנונות ברירת המחדל.
אפשר להגדיר שינויים בעיצוב ב-…/res/values/themes.xml. לדוגמה:
<?xml version="1.0" encoding="utf-8"?> <resources> <style name="BrandedTheme" parent="PlacesMaterialTheme"> <!-- Color tokens. --> <item name="placesColorOnNeutralContainer">#5300e8</item> <item name="placesColorOnNeutralContainerVariant">#ee6002</item> ... <!-- Typography tokens. --> <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item> <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item> ... <!-- Spacing tokens. --> <item name="placesSpacingSmall">6dp</item> <item name="placesSpacingMedium">12dp</item> ... <!-- Attribution tokens. --> <item name="placesColorAttributionLightTheme">white</item> <item name="placesColorAttributionDarkTheme">black</item> </style> </resources>
אחר כך אפשר להפנות לסגנונות של שינוי ברירת המחדל באמצעות קריאה ל-setAutocompleteUiCustomization:
ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent(intent); Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); ... } } } ); Intent placeAutocompleteIntent = new PlaceAutocomplete.IntentBuilder() .setInitialQuery("INSERT_QUERY_TEXT") .setOrigin(new LatLng(10.0, 10.0)) ... .setAutocompleteUiCustomization( AutocompleteUiCustomization.builder() .listItemIcon(AutocompleteUiIcon.noIcon()) .listDensity(AutocompleteListDensity.MULTI_LINE) .theme(R.style.BrandedTheme) .build()) .build(this); placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);
קבלת חיזויים של מקומות באופן פרוגרמטי
האפליקציה יכולה לקבל רשימה של שמות מקומות או כתובות חזויים מ-Autocomplete API על ידי קריאה ל-PlacesClient.findAutocompletePredictions() והעברת אובייקט FindAutocompletePredictionsRequest. בדוגמה הבאה מוצגת קריאה מלאה ל-PlacesClient.findAutocompletePredictions().
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);תשובות של השלמה אוטומטית (חדש)
ה-API מחזיר את הערך
FindAutocompletePredictionsResponse
ב-Task.
האובייקט FindAutocompletePredictionsResponse מכיל רשימה של עד חמישה אובייקטים מסוג AutocompletePrediction שמייצגים מקומות שחזיתם נחזתה. יכול להיות שהרשימה תהיה ריקה אם אין מקום מוכר שתואם לשאילתה ולקריטריונים של המסנן.
לכל מקום שחזיתם, אתם יכולים להפעיל את השיטות הבאות כדי לאחזר את פרטי המקום:
-
getFullText(CharacterStyle)מחזירה את הטקסט המלא של תיאור מקום. זהו שילוב של הטקסט הראשי והטקסט המשני. לדוגמה: "מגדל אייפל, שדרות אנטול פראנס, פריז, צרפת". בנוסף, השיטה הזו מאפשרת לכם להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שתבחרו, באמצעותCharacterStyle. הפרמטרCharacterStyleהוא אופציונלי. אם לא רוצים להדגיש שום דבר, מגדירים את הערך כ-null. -
getPrimaryText(CharacterStyle)מחזירה את הטקסט העיקרי שמתאר מקום. בדרך כלל זה השם של המקום. דוגמאות: מגדל אייפל ו-123 Pitt Street. -
getSecondaryText(CharacterStyle)מחזירה את הטקסט המשני של תיאור מקום. השדה הזה שימושי, למשל, כשורה שנייה כשמציגים הצעות להשלמת החיפוש. דוגמאות: "Avenue Anatole France, Paris, France", and "Sydney, New South Wales". getPlaceId()מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסטואלי שמזהה באופן ייחודי מקום מסוים. אפשר להשתמש בו כדי לאחזר את אובייקטPlaceשוב מאוחר יותר. מידע נוסף על מזהי מקומות בהשלמה אוטומטית זמין במאמר פרטי מקום (חדש). מידע כללי על מזהי מקומות זמין במאמר סקירה כללית על מזהי מקומות.-
getTypes()מחזיר את רשימת סוגי המקומות שמשויכים למקום הזה. getDistanceMeters()מחזירה את המרחק בקו ישר במטרים בין המקום הזה לבין נקודת המוצא שצוינה בבקשה.
פרמטרים נדרשים
-
שאילתה
מחרוזת הטקסט שרוצים לחפש. אפשר לציין מילים מלאות ומחרוזות משנה, שמות של מקומות, כתובות ו-Plus Codes. שירות ההשלמה האוטומטית (החדש) מחזיר התאמות אפשריות על סמך המחרוזת הזו ומסדר את התוצאות לפי מידת הרלוונטיות שלהן.
כדי להגדיר את פרמטר השאילתה, צריך להפעיל את ה-method
setQuery()כשיוצרים את האובייקטFindAutocompletePredictionsRequest.
פרמטרים אופציונליים
-
סוגים ראשיים
רשימה של עד חמישה ערכים של סוגי מקומות מטבלה א' או מטבלה ב', שמשמשים לסינון המקומות שמוחזרים בתגובה. כדי שמקום ייכלל בתגובה, הוא חייב להתאים לאחד מערכי הסוג הראשי שצוינו.
למקום יכול להיות רק סוג ראשי אחד מתוך הסוגים שמשויכים לטבלה א' או לטבלה ב'. לדוגמה, הסוג הראשי יכול להיות
"mexican_restaurant"או"steak_house".הבקשה נדחית עם השגיאה
INVALID_REQUESTאם:- צוינו יותר מחמישה סוגים.
- המערכת מציינת סוגים לא מזוהים.
כדי להגדיר את הפרמטר primary types, קוראים לשיטה
setTypesFilter()כשיוצרים את האובייקטFindAutocompletePredictionsRequest. -
מדינות
הצגת תוצאות רק מרשימת המדינות שצוינו, שמוגדרת כרשימה של עד 15 ערכי ccTLD (דומיין ברמה העליונה) באורך שני תווים. אם משמיטים את הפרמטר, לא חלות הגבלות על התגובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:
אם מציינים גם את
locationRestrictionוגם אתincludedRegionCodes, התוצאות יהיו באזור החפיפה של שתי ההגדרות.כדי להגדיר את הפרמטר countries, צריך להפעיל את ה-method
setCountries()כשיוצרים את האובייקטFindAutocompletePredictionsRequest. -
היסט קלט
היסט תווי Unicode מבוסס-אפס שמציין את מיקום הסמן בשאילתה. מיקום הסמן יכול להשפיע על התחזיות שמוחזרות. אם השדה ריק, ברירת המחדל היא אורך השאילתה.
כדי להגדיר את פרמטר ההיסט של הקלט, צריך לבצע קריאה ל-method
setInputOffset()כשיוצרים את האובייקטFindAutocompletePredictionsRequest. הטיה לפי מיקום או הגבלת מיקום
כדי להגדיר את אזור החיפוש, אפשר לציין העדפת מיקום או הגבלת מיקום, אבל לא את שתיהן. אפשר לחשוב על הגבלת מיקום כציון האזור שהתוצאות חייבות להיות בתוכו, ועל הטיית מיקום כציון האזור שהתוצאות חייבות להיות קרובות אליו. ההבדל העיקרי הוא שעם הטיה לפי מיקום, יכול להיות שיוחזרו תוצאות מחוץ לאזור שצוין.
הטיית מיקום
מציין אזור לחיפוש. המיקום הזה משמש כהטיה, לא כמגבלה, כך שעדיין יכול להיות שיוחזרו תוצאות מחוץ לאזור שצוין.
כדי להגדיר את הפרמטר של הטיית המיקום, מפעילים את ה-method
setLocationBias()כשיוצרים את האובייקטFindAutocompletePredictionsRequest.הגבלת מיקום
מציין אזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין.
כדי להגדיר את פרמטר הגבלת המיקום, צריך לבצע קריאה ל-method
setLocationRestriction()כשיוצרים את האובייקטFindAutocompletePredictionsRequest.
מציינים את האזור של הטיית המיקום או הגבלת המיקום כחלון תצוגה מלבני או כעיגול.
מעגל מוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.0, כולל. ערך ברירת המחדל הוא 0.0. כדי להגביל את המיקום, צריך להגדיר את הרדיוס לערך שגדול מ-0.0. אחרת, הבקשה לא מחזירה תוצאות.
מלבן הוא אזור תצוגה של קווי רוחב ואורך, שמיוצג כשני קודקודים מנוגדים באלכסון
lowו-high. אזור התצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. גבולות קו הרוחב חייבים להיות בין -90 ל-90 מעלות, כולל, וגבולות קו האורך חייבים להיות בין -180 ל-180 מעלות, כולל:- אם
low=high, אזור התצוגה מורכב מהנקודה היחידה הזו. - אם
low.longitude>high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך של 180 מעלות). - אם
low.longitude= -180 מעלות ו-high.longitude= 180 מעלות, אזור התצוגה כולל את כל קווי האורך. - אם
low.longitude= 180 מעלות ו-high.longitude= -180 מעלות, טווח קווי האורך ריק.
צריך למלא את שני השדות
lowו-high, והתיבה המיוצגת לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.- אם
-
מקור
נקודת המוצא שממנה מחושב המרחק בקו ישר אל היעד (הגישה אליה מתבצעת באמצעות
getDistanceMeters()). אם הערך הזה מושמט, המרחק בקו ישר לא יוחזר. צריך לציין את המיקום כקואורדינטות של קו רוחב וקו אורך:כדי להגדיר את הפרמטר origin, צריך להפעיל את ה-method
setOrigin()כשיוצרים את האובייקטFindAutocompletePredictionsRequest. -
קוד אזור
קוד האזור שמשמש לעיצוב התגובה, כולל עיצוב הכתובת, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, עם כמה חריגים בולטים. לדוגמה, ה-ccTLD של בריטניה הוא uk (.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'בריטניה וצפון אירלנד').
אם מציינים קידומת חיוג אזורית לא חוקית, ה-API מחזיר שגיאה
INVALID_ARGUMENT. הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.כדי להגדיר את הפרמטר של קוד האזור, צריך להפעיל את ה-method
setRegionCode()כשיוצרים את האובייקטFindAutocompletePredictionsRequest. -
טוקן לסשן
טוקנים לסשנים הם מחרוזות שנוצרות על ידי המשתמשים, שמאפשרות לעקוב אחרי קריאות להשלמה אוטומטית (חדשה) – גם קריאות שבוצעו דרך הווידג'ט וגם קריאות פרוגרמטיות – בתור "סשנים". ההשלמה האוטומטית משתמשת בטוקנים לסשנים כדי לקבץ את שלבי השאילתה והבחירה של חיפוש בהשלמה אוטומטית של משתמש לסשן נפרד לצורכי חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום. בכל סשן יכולות להיות כמה שאילתות, ואחריהן בחירה של מקום אחד. אחרי שהסשן מסתיים, האסימון כבר לא תקף. האפליקציה צריכה ליצור אסימון חדש לכל סשן. אנחנו ממליצים להשתמש בטוקנים לסשנים בכל הסשנים הפרוגרמטיים של ההשלמה האוטומטית (כשמטמיעים קטע קוד או מפעילים השלמה אוטומטית באמצעות Intent, ה-API מטפל בזה באופן אוטומטי).
ההשלמה האוטומטית משתמשת ב-
AutocompleteSessionTokenכדי לזהות כל סשן. האפליקציה צריכה להעביר טוקן סשן חדש בתחילת כל סשן חדש, ואז להעביר את אותו טוקן, יחד עם מזהה מקום, בקריאה הבאה אלfetchPlace()כדי לאחזר את פרטי המקום שנבחר על ידי המשתמש.כדי להגדיר את הפרמטר של טוקן הסשן, צריך לבצע קריאה ל-method
setSessionToken()כשיוצרים את האובייקטFindAutocompletePredictionsRequest.מידע נוסף זמין במאמר טוקנים לסשנים.
דוגמאות להשלמה אוטומטית (חדש)
שימוש בהגבלת מיקום ובהטיית מיקום
כברירת מחדל, ההשלמה האוטומטית (חדש) משתמשת בהטיה לפי כתובת IP כדי לשלוט באזור החיפוש. בשיטת הטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות. אפשר להשתמש בהגבלת מיקום או בהטיית מיקום, אבל לא בשתיהן, כדי לציין אזור לחיפוש.
הגבלת המיקום מציינת את האזור שבו יתבצע החיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין. בדוגמה הבאה נעשה שימוש בהגבלת מיקום כדי להגביל את הבקשה להגבלת מיקום מעגלית ברדיוס של 5,000 מטרים, שמרכזה בסן פרנסיסקו:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);כשמשתמשים בהטיה לפי מיקום, המיקום משמש כהטיה, כלומר יכול להיות שיוחזרו תוצאות שמסביב למיקום שצוין, כולל תוצאות מחוץ לאזור שצוין. בדוגמה הבאה משנים את הבקשה הקודמת כדי להשתמש בהטיה לפי מיקום:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);שימוש בסוגים ראשיים
אתם יכולים להשתמש בפרמטר primary types כדי להגביל את התוצאות של בקשה לסוג מסוים, כמו שמפורט בטבלה א' ובטבלה ב'. אפשר לציין מערך של עד חמישה ערכים. אם לא מציינים סוג, מוחזרים כל הסוגים.
בדוגמה הבאה מצוינת מחרוזת שאילתה של 'כדורגל', והפרמטר primary_types משמש להגבלת התוצאות למקומות מסוג "sporting_goods_store":
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);אם לא מציינים את הפרמטר primary_types, התוצאות יכולות לכלול עסקים מסוגים שלא רוצים, כמו "athletic_field".
שימוש במקור
כשכוללים בבקשה את הפרמטר origin, שמצוין כקואורדינטות של קו רוחב וקו אורך, ה-API כולל בתגובה את המרחק בקו אווירי מנקודת המוצא ליעד (אפשר לגשת אליו באמצעות getDistanceMeters()). בדוגמה הזו, נקודת המוצא מוגדרת למרכז סן פרנסיסקו:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);אופטימיזציה של השלמה אוטומטית (חדש)
בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המקסימום משירות ההשלמה האוטומטית (החדש).
הנה כמה הנחיות כלליות:
- הדרך הכי מהירה לפתח ממשק משתמש תקין היא להשתמש בווידג'ט Autocomplete (חדש) של Maps JavaScript API, בווידג'ט Autocomplete (חדש) של Places SDK ל-Android או בווידג'ט Autocomplete (חדש) של Places SDK ל-iOS.
- להבין את שדות הנתונים החיוניים של ההשלמה האוטומטית (חדש) כבר מההתחלה.
- השדות "הטיה לפי מיקום" ו"הגבלת מיקום" הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
- כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה אם ה-API יחזיר שגיאה.
- חשוב לוודא שהאפליקציה מטפלת במצב שבו לא נבחרה אפשרות, ומציעה למשתמשים דרך להמשיך.
שיטות מומלצות לאופטימיזציה של עלויות
אופטימיזציה בסיסית של עלויות
כדי לבצע אופטימיזציה של העלות של השימוש בשירות Autocomplete (חדש), צריך להשתמש במסכות שדות בווידג'טים Place Details (חדש) ו-Autocomplete (חדש) כדי להחזיר רק את שדות הנתונים של Autocomplete (חדש) שאתם צריכים.
אופטימיזציה מתקדמת של עלויות
כדאי לשקול הטמעה פרוגרמטית של Autocomplete (חדש) כדי לגשת אל מק"ט: תמחור של בקשות להשלמה אוטומטית ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום Place Details (חדש). תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לפי סשן אם שני התנאים הבאים מתקיימים:
- אם אתם צריכים רק את קו הרוחב וקו האורך או את הכתובת של המקום שהמשתמש בחר, תוכלו לקבל את המידע הזה באמצעות Geocoding API במחיר נמוך יותר מאשר קריאה ל-Place Details (New).
- אם משתמשים בוחרים תחזית של השלמה אוטומטית בממוצע של ארבע בקשות או פחות לתחזיות של השלמה אוטומטית (חדשה), התמחור לפי בקשה יכול להיות חסכוני יותר מהתמחור לפי סשן.
האם האפליקציה דורשת מידע נוסף מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
כן, צריך עוד פרטים
שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם פרטי מקום (חדש).
מכיוון שהאפליקציה שלכם דורשת Place Details (חדש), כמו שם המקום, הסטטוס של העסק
או שעות הפעילות, ההטמעה של ההשלמה האוטומטית (חדש) צריכה להשתמש בטוקן לסשן
(באופן פרוגרמטי או מובנה בווידג'טים של
JavaScript,
Android
או iOS)
לכל סשן, בנוסף למק"טים הרלוונטיים של מקומות,
בהתאם לשדות הנתונים של המקומות שאתם מבקשים.1
הטמעה של ווידג'טים
ניהול הסשנים מוטמע אוטומטית בווידג'טים של
JavaScript,
Android,
או iOS. הבקשה כוללת גם את הבקשות של השלמה אוטומטית (חדש) וגם את הבקשה של Place Details (חדש) לגבי הצעות להשלמת החיפוש שנבחרו. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים.
הטמעה פרוגרמטית
משתמשים בטוקן לסשן בבקשות של ההשלמה האוטומטית (חדש). כששולחים בקשה לפרטי מקום (חדש) לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מהתשובה של Autocomplete (חדש)
- הטוקן לסשן שמשמש בבקשה של ההשלמה האוטומטית (חדש)
- הפרמטר
fieldsשמציין את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים
לא, צריך רק כתובת ומיקום
יכול להיות ש-Geocoding API יהיה אפשרות חסכונית יותר מ-Place Details (חדש) לאפליקציה שלכם, בהתאם לביצועים של השימוש ב-Autocomplete (חדש). היעילות של ההשלמה האוטומטית (חדש) בכל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, למקום שבו משתמשים באפליקציה ולשאלה אם הוטמעו שיטות מומלצות לאופטימיזציה של הביצועים.
כדי לענות על השאלה הבאה, צריך לנתח כמה תווים משתמש מקליד בממוצע לפני שהוא בוחר חיזוי של השלמה אוטומטית (חדשה) באפליקציה.
האם המשתמשים בוחרים חיזוי של השלמה אוטומטית (חדשה) בארבע בקשות או פחות, בממוצע?
כן
מטמיעים את Autocomplete (חדש) באופן פרוגרמטי בלי טוקנים לסשן, ומפעילים את Geocoding API על החיזוי של המקום שנבחר.
Geocoding API מספק כתובות וקואורדינטות של קווי רוחב ואורך.
אם שולחים ארבע בקשות של Autocomplete Requests וקריאה אחת ל-Geocoding API לגבי החיזוי של המקום שנבחר, העלות נמוכה יותר מהעלות של Autocomplete (חדש) לכל סשן.1
כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים גם אם הם מקלידים פחות תווים.
לא
שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם Place Details (חדש).
מכיוון שהמספר הממוצע של הבקשות שאתם צפויים לשלוח לפני שמשתמש בוחר חיזוי של השלמה אוטומטית (חדשה) חורג מהעלות של התמחור לכל סשן, ההטמעה של ההשלמה האוטומטית (חדשה) צריכה להשתמש בטוקן לסשן גם לבקשות של ההשלמה האוטומטית (חדשה) וגם לבקשות המשויכות של פרטי מקום (חדש)
לכל סשן.
1
הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים של
JavaScript,
Android
או iOS. הבקשות האלה כוללות גם את הבקשות של השלמה אוטומטית (חדש) וגם את הבקשות של Place Details (חדש) לגבי הצעות להשלמת החיפוש שנבחרו. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את השדות שאתם צריכים.
הטמעה פרוגרמטית
משתמשים בטוקן סשן עם הבקשות של Autocomplete (חדש).
כשמבקשים Place Details (חדש) לגבי התחזית שנבחרה, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מהתגובה של ההשלמה האוטומטית (חדש)
- הטוקן לסשן שמשמש בבקשה של ההשלמה האוטומטית (חדש)
- הפרמטר
fieldsשמציין שדות כמו כתובת וגיאומטריה
כדאי לשקול לעכב את הבקשות להשלמה אוטומטית (חדשה)
אפשר להשתמש באסטרטגיות כמו עיכוב של בקשה להשלמה אוטומטית (חדשה) עד שהמשתמש מקליד את שלושת או ארבעת התווים הראשונים, כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, אם שולחים בקשות של Autocomplete (New) לכל תו אחרי שהמשתמש מקליד את התו השלישי, והמשתמש מקליד שבעה תווים ואז בוחר הצעה שאתם שולחים עבורה בקשה אחת של Geocoding API, העלות הכוללת תהיה עבור 4 בקשות של Autocomplete (New) לפי בקשה + Geocoding.1
אם עיכוב הבקשות יכול להוריד את הממוצע של הבקשות הפרוגרמטיות מתחת לארבע, אפשר לפעול לפי ההנחיות להטמעה של Autocomplete (חדש) עם ביצועים טובים באמצעות Geocoding API. חשוב לזכור שעיכוב של בקשות יכול להיתפס כזמן אחזור על ידי המשתמש, שאולי מצפה לראות תחזיות עם כל הקשה חדשה על המקשים.
כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים בפחות תווים.
-
למידע על העלויות, קראו את המחירונים של Google Maps Platform.
שיטות מומלצות לשיפור הביצועים
בהמשך מפורטות שיטות מומלצות לאופטימיזציה של הביצועים של התכונה 'השלמה אוטומטית (חדשה)':
- מוסיפים להטמעה של ההשלמה האוטומטית (חדש) הגבלות לפי מדינה, הטיה לפי מיקום והעדפת שפה (להטמעות פרוגרמטיות). אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מהדפדפן או מהמכשיר הנייד של המשתמש.
- אם ההשלמה האוטומטית (חדש) מלווה במפה, אתם יכולים להטות את המיקום לפי אזור התצוגה של המפה.
- במצבים שבהם משתמש לא בוחר באחד מהחיזויים של ההשלמה האוטומטית (חדשה), בדרך כלל כי אף אחד מהחיזויים האלה לא מתאים לכתובת התוצאה הרצויה, אפשר לעשות שימוש חוזר בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
- אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, תוכלו להשתמש מחדש בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
- אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, תשתמשו בבקשה של Place Details (חדש). אם התוצאות צפויות רק באזור ספציפי, השתמשו בהטיית מיקום.
- משתמשים שמזינים כתובות של יחידות משנה, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת בצ'כיה "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה האוטומטית (החדשה).
- משתמשים שמזינים כתובות עם קידומות של קטעי כביש, כמו "23-30 29th St, Queens" בניו יורק או "47-380 Kamehameha Hwy, Kaneohe" באי קאואיי בהוואי.
הטיה של מיקום
כדי להטות את התוצאות לאזור מסוים, מעבירים פרמטר location ופרמטר radius. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדש) להעדיף להציג תוצאות בתוך האזור שהוגדר. יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר. אפשר להשתמש בפרמטר includedRegionCodes כדי לסנן את התוצאות ולהציג רק מקומות במדינה מסוימת.
הגבלת מיקום
כדי להגביל את התוצאות לאזור מסוים, מעבירים פרמטר locationRestriction.
אפשר גם להגביל את התוצאות לאזור שמוגדר על ידי location ופרמטר radius, על ידי הוספת הפרמטר locationRestriction. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדשה) להחזיר רק תוצאות באזור הזה.