‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

בחירת פלטפורמה: Android iOS JavaScript Web Service

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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

(אופציונלי) מגדירים טוקן לסשן. אם לא תספקו טוקן לסשן, הווידג'ט ייצור אחד בשבילכם.
מגדירים autocompleteIntent עם הפרמטרים הרצויים והטוקן לסשן.
מגדירים ActivityResultLauncher ל-StartActivityForResult. המשגר הזה יטפל בתוצאה שהוחזרה מהפעילות של ההשלמה האוטומטית.
מטפלים בתוצאה בקריאה החוזרת (callback) של ActivityResultLauncher. התהליך הזה כולל חילוץ של AutocompletePrediction ו-AutocompleteSessionToken (אם לא סיפקתם ערכים משלכם), טיפול בשגיאות ושליחת בקשה אופציונלית של fetchPlace() כדי לקבל פרטים נוספים על מקום.
מפעילים את ה-intent באמצעות 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());
        })
    );

הערה: למידע נוסף על הפעלת PlacesClient, ראו הפעלת לקוח Places API.

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

ה-API מחזיר FindAutocompletePredictionsResponse ב-Task. השדה FindAutocompletePredictionsResponse מכיל רשימה של עד חמישה אובייקטים מסוג AutocompletePrediction שמייצגים מקומות חזויים. הרשימה יכולה להיות ריקה אם אין מקום מוכר שתואם לשאילתה ולקריטריונים של הסינון.

לכל מקום חזוי, אפשר להפעיל את השיטות הבאות כדי לאחזר את פרטי המקום:

getFullText(CharacterStyle) מחזירה את הטקסט המלא של תיאור המקום. זה שילוב של הטקסט הראשי והמשני. לדוגמה: "מגדל אייפל, שדרות אנטול פראנס, פריז, צרפת". בנוסף, השיטה הזו מאפשרת להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון לבחירתכם, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. אם אתם לא רוצים להדגיש שום דבר, הגדירו את הערך null.
getPrimaryText(CharacterStyle) מחזירה את הטקסט הראשי שמתאר מקום. בדרך כלל זה השם של המקום. דוגמאות: "מגדל אייפל" ו "רחוב רוטשילד 123".
getSecondaryText(CharacterStyle) מחזירה את הטקסט המשני של תיאור המקום. השדה הזה שימושי, למשל, כשורה שנייה כשמציגים הצעות להשלמת החיפוש. דוגמאות: "Avenue Anatole France, Paris, France" ו-"Sydney, New South Wales".
getPlaceId() מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי, ואפשר להשתמש בו כדי לאחזר את האובייקט Place שוב מאוחר יותר. מידע נוסף על מזהי מקומות בהשלמה האוטומטית זמין במאמר פרטי מקום (חדש). למידע כללי על מזהי מקומות, קראו את הסקירה הכללית על מזהי מקומות.
‫getTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
getDistanceMeters() מחזירה את המרחק בקו ישר במטרים בין המקום הזה לבין נקודת המוצא שצוינה בבקשה.

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

שאילתה

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

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

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

סוגים ראשיים

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

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

הבקשה תידחה ותוצג השגיאה INVALID_REQUEST אם:

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

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

מדינות

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

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

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

היסט קלט

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

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

העדפת מיקום או הגבלת מיקום

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

הטיית מיקום

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

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

מציין אזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין.

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

מציינים את האזור של העדפת המיקום או הגבלת המיקום כ-Viewport מלבני או כעיגול.

מעגל מוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.0, כולל. ערך ברירת המחדל הוא 0.0. כדי להגביל את המיקום, צריך להגדיר את הרדיוס לערך שגדול מ-0.0. אחרת, הבקשה לא תחזיר תוצאות.
מלבן הוא אזור תצוגה של קו רוחב וקו אורך, שמיוצג כשתי נקודות low ו-high מנוגדות באלכסון. אזור תצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבולות שלו. גבולות קו הרוחב חייבים להיות בין ‎-90 ל-90 מעלות, כולל, וגבולות קו האורך חייבים להיות בין ‎-180 ל-180 מעלות, כולל:

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

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

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

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

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

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

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

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

כדי לבחור את ההטמעה של Autocomplete (New)‎ שהכי משתלמת לאפליקציה שלכם, חפשו בטבלה הבאה את השורה שמתאימה לצרכים של האפליקציה.

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

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

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

השלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש)

שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם פרטי מקום (חדשים).
מכיוון שהאפליקציה שלכם דורשת פרטי מקום (חדש), כמו שם המקום, סטטוס העסק או שעות הפעילות, ההטמעה של ההשלמה האוטומטית (חדש) צריכה להשתמש בטוקן לסשן (באופן פרוגרמטי או מובנה בווידג'טים של JavaScript, Android או iOS) לכל סשן, בנוסף למק"טים הרלוונטיים של Places, בהתאם לשדות של נתוני המקומות שאתם מבקשים.¹

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

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

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

השלמה אוטומטית (חדשה) לכל בקשה באמצעות Geocoding API

מטמיעים את Autocomplete (חדש) באופן פרוגרמטי בלי טוקנים לסשנים, וקוראים ל-Geocoding API בחיזוי המקום שנבחר.
‫Geocoding API מספק כתובות וקואורדינטות של קווי רוחב ואורך. שליחת ארבע בקשות של Autocomplete Requests וקריאה אחת ל-Geocoding API לגבי החיזוי של המקום שנבחר עולה פחות מהעלות של Autocomplete (חדש) לכל סשן.¹

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

השלמה אוטומטית (חדשה) מבוססת-סשן לאפליקציות של כתובות בלבד

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

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

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

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

כדאי לשקול לעכב את הבקשות להשלמה אוטומטית (חדשה)
אפשר להשתמש באסטרטגיות כמו עיכוב של בקשה להשלמה אוטומטית (חדשה) עד שהמשתמש מקליד את שלושת או ארבעת התווים הראשונים, כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, אם שולחים בקשות של Autocomplete (New)‎ לכל תו אחרי שהמשתמש מקליד את התו השלישי, והמשתמש מקליד שבעה תווים ואז בוחר הצעה שבעקבותיה נשלחת בקשה אחת של Geocoding API, העלות הכוללת תהיה על 4 בקשות של Autocomplete (New)‎ לפי בקשה + Geocoding.¹

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

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

למידע על העלויות, קראו את המחירונים של Google Maps Platform.

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

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

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

הטיית מיקום

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

אזהרה: אם לא מציינים את radius, המערכת מתעלמת מהפרמטר location.

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

הגבלת מיקום

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

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

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

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

Kotlin

Java

התאמה אישית של העיצוב

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

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

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

שאילתה

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

סוגים ראשיים

מדינות

היסט קלט

העדפת מיקום או הגבלת מיקום

הטיית מיקום

הגבלת מיקום

מקור

קוד אזור

טוקן לסשן

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

שימוש בהגבלת מיקום ובהטיית מיקום

שימוש בסוגים ראשיים

שימוש במקור

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

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

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

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

השלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש)

השלמה אוטומטית (חדשה) לכל בקשה באמצעות Geocoding API

השלמה אוטומטית (חדשה) מבוססת-סשן לאפליקציות של כתובות בלבד

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

הטיית מיקום

הגבלת מיקום

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