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

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

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

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

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

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

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

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

קבלת תחזיות לגבי מקומות באופן פרוגרמטי

האפליקציה יכולה לקבל רשימה של שמות או כתובות של מקומות שחזויים על ידי ה-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) מחזירה את הטקסט העיקרי שמתאר מקום. בדרך כלל זה השם של המקום. דוגמאות: ‎"Eiffel Tower"‎ ו-‎ "123 Pitt Street"‎.
• ‫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, שמשמשים לסינון המקומות שמוחזרים בתשובה. כדי שמקום ייכלל בתשובה, הוא צריך להתאים לאחד מהערכים שצוינו לסוג הראשי.

  למקום יכול להיות רק סוג ראשי אחד מתוך הסוגים 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() כדי לאחזר את Place Details עבור המקום שנבחר על ידי המשתמש.

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

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

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

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

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

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

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

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

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

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

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

הטיה של מיקום

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

הגבלת מיקום

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

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