הדור הבא של Places SDK עבור Android זמין עכשיו עם המהדורה של Places SDK ל-Android (חדש).

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

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

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

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

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

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

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

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

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

אפשרות 1: הטמעת AutocompleteSupportFragment.
אפשרות 2: שימוש בכוונה (intent) כדי להפעיל את הפעילות של ההשלמה האוטומטית.

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

כדי להוסיף AutocompleteSupportFragment לאפליקציה:

מוסיפים קטע לפריסה של ה-XML בפעילות.
מוסיפים מאזין לפעילות או לקטע.

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

כדי להוסיף את AutocompleteSupportFragment לפעילות, מוסיפים קטע חדש לפריסה של קובץ ה-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"
  />

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

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

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

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**: ווידג'ט של השלמה אוטומטית במצב שכבת-על

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

הרשמה לקריאה חוזרת (callback) לתוצאת הכוונה

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

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

אתם יכולים ליצור ממשק משתמש מותאם אישית לחיפוש, כחלופה לממשק המשתמש שסופק על ידי הווידג'ט של ההשלמה האוטומטית. כדי לעשות זאת, האפליקציה צריכה לקבל תחזיות למיקומים באופן פרוגרמטי. כדי לקבל מה-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) מחזירה את הטקסט המלא של תיאור מקום. זהו שילוב של הטקסט הראשי והטקסט המשני. דוגמה: מגדל אייפל, שדרת Anatole France, פריז, צרפת. בנוסף, השיטה הזו מאפשרת להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שבחרתם, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. מגדירים אותו כ-null אם לא צריך הדגשה.
getPrimaryText(CharacterStyle) מחזירה את הטקסט הראשי שמתאר מקום. בדרך כלל זהו שם המקום. דוגמאות: 'מגדל אייפל' ו'רחוב Pitt‏ 123'.
getSecondaryText(CharacterStyle) מחזירה את הטקסט המשני של תיאור מקום. לדוגמה, אפשר להשתמש בה כשורה שנייה כשמציגים חיזויים של השלמה אוטומטית. דוגמאות: Avenue Anatole France, Paris, France ו-Sydney, New South Wales.
getPlaceId() מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסט שמזהה באופן ייחודי מקום מסוים. אפשר להשתמש בו כדי לאחזר את האובייקט Place מאוחר יותר. מידע נוסף על מזהי מקומות ב-Places SDK ל-Android זמין במאמר פרטי מקום. למידע כללי על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.
הפונקציה getPlaceTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
הפונקציה getDistanceMeters() מחזירה את המרחק בקו ישר, במטרים, בין המקום הזה לבין נקודת המוצא שצוינה בבקשה.

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

אסימוני סשן

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

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

מידע נוסף על אסימוני סשן

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

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

כדי להגביל את התוצאות:

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

הטיה של התוצאות לאזור ספציפי

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

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

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() ומציינים type collection מהטבלה 3 שמופיעה בקטע Place Types. ערכי האוסף מוגדרים על ידי הקבועים ב-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(). לאחר מכן מעבירים את המסנן לקטע קוד או לכוונה. צריך להעביר את המדינות כקוד מדינה בן שתי אותיות שתואם לתקן 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, בווידג'ט להשלמה אוטומטית של Places SDK ל-Android או ברכיב הבקרה של ממשק המשתמש להשלמה אוטומטית של Places SDK ל-iOS.
כבר מההתחלה, חשוב להבין את שדות הנתונים החיוניים של השלמה אוטומטית של מקומות.
השדות של הטיית המיקום וההגבלה על המיקום הם אופציונליים, אבל הם יכולים להשפיע באופן משמעותי על הביצועים של ההשלמה האוטומטית.
השתמשו בניהול שגיאות כדי לוודא שהאפליקציה תמשיך לפעול בצורה חלקה אם ה-API מחזיר שגיאה.
חשוב לוודא שהאפליקציה מטפלת במקרים שבהם לא בוצעה בחירה ומציעה למשתמשים דרך להמשיך.

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

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

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

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

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

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

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

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

כן, נדרשים פרטים נוספים

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

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

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

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

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

יכול להיות ש-Geocoding API תהיה אפשרות חסכונית יותר מ'פרטי מקום' לאפליקציה שלכם, בהתאם לביצועים של השימוש בתכונה 'השלמה אוטומטית של מקום'. היעילות של השלמה אוטומטית בכל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, לאזור שבו האפליקציה נמצאת בשימוש ולשיטות המומלצות לאופטימיזציה של הביצועים שהוחלו.

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

האם המשתמשים בוחרים חיזוי של מקום בהשלמה אוטומטית בארבע בקשות או פחות, בממוצע?

כן

מטמיעים את ההשלמה האוטומטית של מקומות באופן פרוגרמטי בלי אסימוני סשן, ומפעילים את Geocoding API על תחזית המיקום שנבחרה.
Geocoding API מספק כתובות וקואורדינטות של קווי אורך ורוחב תמורת 0.005 $לכל בקשה. שליחת ארבע בקשות Place Autocomplete – Per Request עולה 0.01132$, כך שהעלות הכוללת של ארבע הבקשות וקריאה ל-Geocoding API לגבי תחזית המקום שנבחרה היא 0.01632$, נמוכה מהמחיר של השלמת האוטומטית 'לכל סשן', 0.017 $לכל סשן.¹

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

לא

שימוש בהשלמה אוטומטית של מקומות מבוססת-סשן עם פרטי מקומות
מאחר שמספר הבקשות הממוצע שאתם צפויים לשלוח לפני שמשתמש יבחר תחזית של Place Autocomplete חורג מהעלות של התמחור 'לסשן', בהטמעה של Place Autocomplete צריך להשתמש באסימון סשן גם לבקשות של Place Autocomplete וגם לבקשה המשויכת של פרטי המקום, בעלות כוללת של 0.017 $לסשן.¹

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

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

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

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

העלויות שמפורטות כאן הן בדולר ארה"ב. מידע מלא על התמחור זמין בדף חיוב בפלטפורמה של מפות Google.

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

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

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

פתרון בעיות

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

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