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

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

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

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

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

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

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

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

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

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

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

הוספת 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:

    // 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")
        }
    })

      

    // 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).

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

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

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

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

    // 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)

      

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

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

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

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")
        }
    }

      

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().

    // 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}")
            }
        }

      

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

אסימוני סשן

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

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

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

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

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

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

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

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

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

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

      

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

      

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

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

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

      

    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, עם ציון של כמה ערכים של סוגים.

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

      

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

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

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

      

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

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

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

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

      

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

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

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

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

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