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

דף זה תורגם על ידי Cloud Translation API.

השלמה אוטומטית למקומות

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

שירות ההשלמה האוטומטית ב-Places SDK ל-Android מחזיר תחזיות של מקומות בתגובה לשאילתות חיפוש של משתמשים. בזמן שהמשתמש מקליד, שירות ההשלמה האוטומטית מחזיר הצעות למקומות כמו עסקים, כתובות, קודי OLC ונקודות עניין.

אפשר להוסיף השלמה אוטומטית לאפליקציה בדרכים הבאות:

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

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

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

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

אפשרות 1: הטמעת AutocompleteSupportFragment.
אפשרות 2: שימוש ב-Intent להפעלת פעילות ההשלמה האוטומטית.

אפשרות 1: הטמעה של AutocompleteSupportFragment

כדי להוסיף AutocompleteSupportFragment לאפליקציה, פועלים לפי השלבים הבאים:

מוסיפים רכיב Fragment לפריסת ה-XML של הפעילות.
מוסיפים listener לפעילות או לקטע.

הוספת AutocompleteSupportFragment לפעילות

כדי להוסיף AutocompleteSupportFragment לפעילות, מוסיפים רכיב fragment חדש לפריסת XML. לדוגמה:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

כברירת מחדל, למקטע אין גבול או רקע. כדי לספק מראה חזותי עקבי, צריך להציב את ה-Fragment בתוך רכיב פריסה אחר, כמו CardView.
אם אתם משתמשים בקטע הקוד Autocomplete וצריכים לבטל את onActivityResult, אתם צריכים לקרוא ל-super.onActivityResult, אחרת קטע הקוד לא יפעל כמו שצריך.

הוספת PlaceSelectionListener לפעילות

הפונקציה PlaceSelectionListener מטפלת בהחזרת מקום בתגובה לבחירה של המשתמש. בדוגמה הבאה מוצג קוד ליצירת הפניה אל ה-Fragment ולהוספת מאזין אל AutocompleteSupportFragment:

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

אפשרות 2: שימוש ב-Intent להפעלת פעילות ההשלמה האוטומטית

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

כדי להפעיל את הווידג'ט של ההשלמה האוטומטית באמצעות כוונת משתמש, פועלים לפי השלבים הבאים:

משתמשים ב-Autocomplete.IntentBuilder כדי ליצור כוונת רכישה, ומעבירים את מצב Autocomplete הרצוי.
הגדרת כלי להפעלת תוצאה של פעילות registerForActivityResult שאפשר להשתמש בו כדי להפעיל את הכוונה ולטפל בחיזוי המקום שהמשתמש בחר בתוצאה.

יצירת כוונת השלמה אוטומטית

בדוגמה שלמטה נעשה שימוש ב-Autocomplete.IntentBuilder כדי ליצור Intent להפעלת הווידג'ט של ההשלמה האוטומטית כ-Intent:

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

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

כשמוצג במצב שכבת-על, ווידג'ט ההשלמה האוטומטית מופיע כשכבת-על בממשק המשתמש של השיחה. — **תרשים 1**: ווידג'ט להשלמה אוטומטית במצב OVERLAY

כשמוצג במצב מסך מלא, ווידג'ט ההשלמה האוטומטית ממלא את המסך כולו. — **איור 2**: ווידג'ט ההשלמה האוטומטית במצב מסך מלא

הרשמה להתקשרות חוזרת לתוצאת הכוונה

כדי לקבל התראה כשהמשתמש בוחר מקום, צריך להגדיר registerForActivityResult()launcher, שמפעיל את הפעילות ומטפל גם בתוצאה, כמו בדוגמה הבאה. אם המשתמש בחר חיזוי, הוא יועבר בכוונת המשתמש שכלולה באובייקט התוצאה. מכיוון שהכוונה נוצרה על ידי Autocomplete.IntentBuilder, השיטה Autocomplete.getPlaceFromIntent() יכולה לחלץ ממנה את אובייקט המקום.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

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

אתם יכולים ליצור ממשק משתמש מותאם אישית לחיפוש כחלופה לממשק המשתמש שמסופק על ידי הווידג'ט של ההשלמה האוטומטית. כדי לעשות את זה, האפליקציה צריכה לקבל תחזיות לגבי מקומות באופן פרוגרמטי. האפליקציה יכולה לקבל רשימה של שמות מקומות או כתובות חזויים מ-Autocomplete API על ידי קריאה ל-PlacesClient.findAutocompletePredictions(), העברת אובייקט FindAutocompletePredictionsRequest עם הפרמטרים הבאים:

חובה: מחרוזת query שמכילה את הטקסט שהמשתמש הקליד.
מומלץ: AutocompleteSessionToken, שבו שלבי השאילתה והבחירה של חיפוש משתמש מקובצים לסשן נפרד למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום.
מומלץ: אובייקט RectangularBounds שמציין גבולות של קווי רוחב ואורך כדי להגביל את התוצאות לאזור שצוין.
אופציונלי: קוד מדינה אחד או יותר בני שתי אותיות (ISO 3166-1 Alpha-2), שמציין את המדינה או המדינות שבהן צריך להגביל את התוצאות.
אופציונלי: מחרוזת TypeFilter, שאפשר להשתמש בה כדי להגביל את התוצאות לסוג המקום שצוין. אלה סוגי המקומות שנתמכים:
- ‫TypeFilter.GEOCODE – מחזיר רק תוצאות של המרת קואורדינטות לכתובות, ולא עסקים. אפשר להשתמש בבקשה הזו כדי להבהיר תוצאות שבהן המיקום שצוין לא ברור.
- ‫TypeFilter.ADDRESS – מחזיר רק תוצאות של השלמה אוטומטית עם כתובת מדויקת. משתמשים בסוג הזה כשברור שהמשתמש מחפש כתובת מפורטת.
- ‫TypeFilter.ESTABLISHMENT – מחזיר רק מקומות שהם עסקים.
- ‫TypeFilter.REGIONS – מחזירה רק מקומות שתואמים לאחד מהסוגים הבאים:
- LOCALITY
- SUBLOCALITY
- POSTAL_CODE
- COUNTRY
- ADMINISTRATIVE_AREA_LEVEL_1
- ADMINISTRATIVE_AREA_LEVEL_2
- ‫TypeFilter.CITIES – מחזיר רק תוצאות שתואמות ל-LOCALITY או ל-ADMINISTRATIVE_AREA_LEVEL_3.
אופציונלי: LatLng שמציין את מיקום המקור של הבקשה. כשמתקשרים אל setOrigin(), השירות מחזיר את המרחק במטרים (distanceMeters) מנקודת המוצא שצוינה, לכל תחזית להשלמה אוטומטית בתגובה.

מידע על סוגי מקומות זמין במדריך סוגי מקומות.

בדוגמה הבאה מוצגת קריאה מלאה ל-PlacesClient.findAutocompletePredictions().

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

ממשק ה-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 שוב מאוחר יותר. מידע נוסף על מזהי מקומות ב-Places SDK ל-Android זמין במאמר פרטי מקום. מידע כללי על מזהי מקומות זמין במאמר סקירה כללית על מזהי מקומות.
‫getPlaceTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
‫getDistanceMeters() מחזירה את המרחק בקו ישר במטרים בין המקום הזה לבין הנקודה שצוינה בבקשה.

הערה: מידע נוסף על אתחול PlacesClient זמין במאמר בנושא אתחול לקוח Places API.

טוקנים של סשנים

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

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

מידע נוסף על טוקנים של סשנים

הגבלת תוצאות ההשלמה האוטומטית

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

כדי לצמצם את התוצאות:

כדי להעדיף תוצאות מהאזור המוגדר, קוראים ל-setLocationBias() (יכול להיות שעדיין יוחזרו תוצאות מסוימות מחוץ לאזור המוגדר).
כדי להציג רק תוצאות באזור המוגדר, קוראים ל-setLocationRestriction() (רק תוצאות באזור המוגדר יוחזרו).
כדי להחזיר רק תוצאות שתואמות לסוג מסוים של מקום, צריך להתקשר אל setTypesFilter() (לדוגמה, ציון TypeFilter.ADDRESS יחזיר רק תוצאות עם כתובת מדויקת).
כדי לקבל רק תוצאות מתוך עד חמש מדינות ספציפיות, מתקשרים אל setCountries(). המדינות צריכות להיות מועברות כקוד מדינה בן שני תווים שתואם לתקן ISO 3166-1 Alpha-2.

הטיית התוצאות לאזור מסוים

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

Kotlin

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Java

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

הגבלת התוצאות לאזור ספציפי

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

Kotlin

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Java

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

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

סינון התוצאות לפי סוגי מקומות או אוסף סוגים

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

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

כדי לציין מסנן של סוג או אוסף סוגים:

מתקשרים אל setTypesFilter() ומציינים עד חמישה ערכים של type מתוך טבלה 1 וטבלה 2 שמוצגות בסוגי מקומות. ערכי הסוג מוגדרים על ידי הקבועים ב-PlaceTypes.
מתקשרים אל setTypesFilter() ומציינים סוג אוסף מתוך טבלה 3 שמוצגת בסוגי מקומות. הערכים של האוסף מוגדרים על ידי הקבועים ב-PlaceTypes.

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

בדוגמה הבאה של קוד מבוצעת קריאה לפונקציה setTypesFilter() ב-AutocompleteSupportFragment ומצוינים כמה ערכים של סוגים.

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

Java

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

בדוגמה הבאה של קוד מוצגת קריאה ל-setTypesFilter() ב-AutocompleteSupportFragment כדי להגדיר מסנן שמחזיר רק תוצאות עם כתובת מדויקת על ידי ציון אוסף סוגים.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

בדוגמה הבאה של קוד מוצגת קריאה ל-setTypesFilter() ב-IntentBuilder כדי להגדיר מסנן שמחזיר רק תוצאות עם כתובת מדויקת על ידי ציון אוסף סוגים.

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

Java

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

סינון התוצאות לפי מדינה

כדי לסנן את תוצאות ההשלמה האוטומטית כך שיוצגו עד חמש מדינות, מתקשרים אל setCountries() כדי להגדיר את קוד המדינה. לאחר מכן, מעבירים את המסנן לקטע או ל-Intent. המדינות צריכות להיות מועברות כקוד מדינה בן שני תווים שתואם לתקן ISO 3166-1 Alpha-2.

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

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

Java

    autocompleteFragment.setCountries("AU", "NZ");

מגבלות שימוש

השימוש שלכם ב-Places API, כולל Places SDK ל-Android, כבר לא מוגבל למספר מקסימלי של בקשות ביום (QPD). עם זאת, עדיין חלות מגבלות השימוש הבאות:

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

הצגת שיוכים באפליקציה

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

לפרטים נוספים, אפשר לעיין במאמר בנושא שיוכים.

אופטימיזציה של השלמה אוטומטית למקומות (גרסה קודמת)

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

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

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

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

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

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

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

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

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

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

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

כן, צריך פרטים נוספים

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

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

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

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

לא, צריך רק כתובת ומיקום

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

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

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

כן

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

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

לא

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

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

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

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

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

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

למידע על עלויות, אפשר לעיין ברשימות המחירים של הפלטפורמה של מפות Google.

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

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

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

פתרון בעיות

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

שגיאות שמתרחשות בשימוש באמצעי הבקרה של ההשלמה האוטומטית מוחזרות ב-onActivityResult() callback. מתקשרים אל Autocomplete.getStatus() כדי לקבל את הודעת הסטטוס של התוצאה.

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

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

אפשרות 1: הטמעה של AutocompleteSupportFragment

הוספת AutocompleteSupportFragment לפעילות

הוספת PlaceSelectionListener לפעילות

Kotlin

Java

אפשרות 2: שימוש ב-Intent להפעלת פעילות ההשלמה האוטומטית

יצירת כוונת השלמה אוטומטית

Kotlin

Java

הרשמה להתקשרות חוזרת לתוצאת הכוונה

Kotlin

Java

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

Kotlin

Java

טוקנים של סשנים

הגבלת תוצאות ההשלמה האוטומטית

הטיית התוצאות לאזור מסוים

Kotlin

Java

הגבלת התוצאות לאזור ספציפי

Kotlin

Java

סינון התוצאות לפי סוגי מקומות או אוסף סוגים

Kotlin

Java

Kotlin

Java

Kotlin

Java

סינון התוצאות לפי מדינה

Kotlin

Java

מגבלות שימוש

הצגת שיוכים באפליקציה

אופטימיזציה של השלמה אוטומטית למקומות (גרסה קודמת)

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

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

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

כן, צריך פרטים נוספים

לא, צריך רק כתובת ומיקום

כן

לא

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

פתרון בעיות

השלמה אוטומטית למקומות