השלמה אוטומטית (חדשה)

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

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

יש שתי דרכים עיקריות לשלב את הפונקציונליות של ההשלמה האוטומטית (חדשה) באפליקציה:

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

הוספת הווידג'ט של השלמה אוטומטית למקומות

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

בדומה לקבלת חיזויים של מקומות באופן פרוגרמטי, הווידג'ט Place Autocomplete מאפשר להשתמש בטוקנים של סשנים כדי לקבץ בקשות להשלמה אוטומטית לסשן לצורכי חיוב. אפשר להעביר טוקן של סשן כשיוצרים את הכוונה של הווידג'ט על ידי קריאה ל-setAutocompleteSessionToken(). אם לא תספקו אסימון סשן, הווידג'ט ייצור אסימון בשבילכם, ותוכלו לגשת אליו באמצעות הקריאה ל-getSessionTokenFromIntent(). מידע נוסף על השימוש באסימונים של סשנים זמין במאמר מידע על אסימונים של סשנים.

כדי להוסיף את הווידג'ט של השלמה אוטומטית של מקומות לאפליקציה:

1. (אופציונלי) מגדירים טוקן סשן. אם לא תספקו אסימון סשן, הווידג'ט ייצור אסימון בשבילכם.

2. מגדירים autocompleteIntent עם הפרמטרים הרצויים ועם טוקן הסשן.

3. הגדרת ActivityResultLauncher עבור StartActivityForResult. ה-launcher הזה יטפל בתוצאה שמוחזרת מהפעילות של ההשלמה האוטומטית.

4. מטפלים בתוצאה בקריאה החוזרת של ActivityResultLauncher. התהליך כולל חילוץ של AutocompletePrediction ושל AutocompleteSessionToken (אם לא סיפקתם משלכם), טיפול בשגיאות, ואופציונלית שליחה של בקשת fetchPlace() כדי לקבל פרטים נוספים על מקום.

5. הפעלת הכוונה באמצעות placeAutocompleteActivityResultLauncher

בדוגמאות הבאות אפשר לראות איך מוסיפים את הווידג'ט של השלמה אוטומטית של מקומות באמצעות Kotlin ו-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.
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)

// 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) מחזירה את הטקסט המלא של תיאור המקום. זהו שילוב של הטקסט הראשי והמשני. דוגמה: "Eiffel Tower, Avenue Anatole France, Paris, France". בנוסף, השיטה הזו מאפשרת לכם להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שתבחרו, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. אם לא רוצים להדגיש שום דבר, מגדירים את הערך כ-null.
• ‫getPrimaryText(CharacterStyle) מחזירה את הטקסט העיקרי שמתאר מקום. בדרך כלל זה השם של המקום. דוגמאות: מגדל אייפל ורחוב פיט 123.
• ‫getSecondaryText(CharacterStyle) מחזירה את הטקסט המשני של תיאור מקום. לדוגמה, אפשר להשתמש בזה כשמציגים חיזויים של השלמה אוטומטית בשורה השנייה. דוגמאות: 'Avenue Anatole France, Paris, France' ו-'Sydney, New South Wales'.
• ‫getPlaceId() מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסטואלי שמזהה באופן ייחודי מקום מסוים. אפשר להשתמש בו כדי לאחזר את אובייקט Place שוב מאוחר יותר. מידע נוסף על מזהי מקומות ב-Autocomplete זמין במאמר Place Details (חדש). מידע כללי על מזהי מקומות זמין במאמר סקירה כללית על מזהי מקומות.
• ‫getTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
• ‫getDistanceMeters() מחזירה את המרחק בקו ישר במטרים בין המקום הזה לבין המיקום שצוין בבקשה.

פרמטרים נדרשים

• שאילתה

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

  כדי להגדיר את פרמטר השאילתה, קוראים ל-method‏ setQuery() כשיוצרים את האובייקט FindAutocompletePredictionsRequest.

פרמטרים אופציונליים

• סוגים של חשבונות משתמשים

  רשימה של עד חמישה ערכים מסוג type מתוך הסוגים Table A או Table B, שמשמשים לסינון המקומות שמוחזרים בתשובה. כדי שמקום ייכלל בתשובה, הוא צריך להתאים לאחד מהערכים שצוינו לסוג הראשי.

  למקום יכול להיות רק סוג ראשי אחד מתוך הסוגים שמשויכים לטבלה א' או לטבלה ב'. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house".

  הבקשה נדחית עם השגיאה INVALID_REQUEST אם:

  • צוינו יותר מחמישה סוגים.
  • מצוינים סוגים לא מזוהים.

  כדי להגדיר את הפרמטר primary types, צריך לקרוא ל-method‏ setTypesFilter() כשיוצרים את האובייקט FindAutocompletePredictionsRequest.

• מדינות

  אפשר לכלול רק תוצאות מרשימת המדינות שצוינו, שמוגדרות כרשימה של עד 15 ערכים באורך שני תווים של ccTLD (דומיין ברמה העליונה). אם לא מציינים את הפרמטר הזה, לא מוחלות הגבלות על התשובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:

  אם מציינים גם locationRestriction וגם includedRegionCodes, התוצאות יהיו באזור החיתוך של שתי ההגדרות.

  כדי להגדיר את פרמטר המדינות, צריך לבצע קריאה ל-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()). אם הערך הזה לא מצוין, המרחק בקו ישר לא יוחזר. חובה לציין את קואורדינטות קו הרוחב וקו האורך:

  כדי להגדיר את פרמטר המקור, צריך לבצע קריאה ל-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());
        })
    );

אופטימיזציה של השלמה אוטומטית (חדש)

בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המרב מהשירות 'השלמה אוטומטית (חדש)'.

הנה כמה הנחיות כלליות:

• הדרך הכי מהירה לפתח ממשק משתמש תקין היא להשתמש בווידג'ט החדש של השלמה אוטומטית ב-Maps JavaScript API, בווידג'ט החדש של השלמה אוטומטית ב-Places SDK ל-Android או בווידג'ט החדש של השלמה אוטומטית ב-Places SDK ל-iOS.
• הבנה של שדות הנתונים החיוניים של ההשלמה האוטומטית (חדש) כבר מההתחלה.
• השדות 'הטיה לפי מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
• כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה גם אם ה-API יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם לא נבחרה אפשרות, ומציעה למשתמשים דרך להמשיך.

שיטות מומלצות לאופטימיזציה של עלויות

אופטימיזציה בסיסית של עלויות

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

אופטימיזציה מתקדמת של עלויות

כדאי להטמיע את ההשלמה האוטומטית (חדש) באופן פרוגרמטי כדי לגשת אל מזהה SKU: תמחור של בקשות להשלמה אוטומטית ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום פרטי מקום (חדש). התמחור לפי בקשה בשילוב עם Geocoding API הוא חסכוני יותר מהתמחור לפי סשן (מבוסס-סשן) אם מתקיימים שני התנאים הבאים:

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

האם האפליקציה שלך דורשת מידע כלשהו מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?

שיטות מומלצות לשיפור הביצועים

בהנחיות הבאות מפורטות דרכים לאופטימיזציה של הביצועים של התכונה 'השלמה אוטומטית (חדשה)':

• מוסיפים הגבלות לפי מדינה, הטיה לפי מיקום, והעדפת שפה (להטמעות פרוגרמטיות) להטמעה של התכונה 'השלמה אוטומטית (חדשה)'. אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מתוך הדפדפן או המכשיר הנייד של המשתמש.
• אם ההשלמה האוטומטית (חדשה) מופיעה עם מפה, אפשר להטות את המיקום לפי אזור התצוגה של המפה.
• במצבים שבהם משתמש לא בוחר באף אחת מההצעות להשלמה אוטומטית (חדשה), בדרך כלל כי אף אחת מההצעות האלה לא מתאימה לכתובת שהוא מחפש, אפשר להשתמש מחדש בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
  • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, תוכלו להשתמש מחדש בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
  • אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, תשתמשו בבקשה של פרטי מקום (חדש). אם אתם מצפים לתוצאות רק באזור מסוים, כדאי להשתמש בהטיה לפי מיקום.
  תרחישים נוספים שבהם מומלץ לחזור ל-Geocoding API כוללים:
  • משתמשים שמזינים כתובות של יחידות משנה, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת הצ'כית "Stroupežnického 3191/17, Praha" תניב חיזוי חלקי בהשלמה האוטומטית (חדש).
  • משתמשים שמזינים כתובות עם קידומות של קטע כביש כמו "23-30 29th St, Queens" בניו יורק או "47-380 Kamehameha Hwy, Kaneohe" באי קוואי בהוואי.

הטיה של מיקום

כדי להטות את התוצאות לאזור מסוים, מעבירים פרמטר location ופרמטר radius. ההגדרה הזו מורה להשלמה האוטומטית (חדשה) להעדיף הצגת תוצאות באזור המוגדר. יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר. אפשר להשתמש בפרמטר components כדי לסנן את התוצאות ולהציג רק מקומות במדינה שצוינה.

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, מעבירים פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שהוגדר על ידי location והפרמטר radius, על ידי הוספת הפרמטר locationRestriction. ההוראה הזו גורמת להשלמה האוטומטית (חדשה) להחזיר רק תוצאות באזור הזה.