השלמה אוטומטית למקומות (דור קודם)

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

אם כתובת החיוב שלכם נמצאת באזור הכלכלי האירופי, החל מ-8 ביולי 2025, התנאים וההגבלות של Google Maps Platform למשתמשים באזור הכלכלי האירופי יחולו על השימוש שלכם בשירותים. הפונקציונליות יכולה להיות שונה בין אזור לאזור. מידע נוסף

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

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

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

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

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

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

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

הוספת 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

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

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

הערה: אין צורך לבצע את השלבים האלה אם אתם מטמיעים קטע קוד.

זהירות: אל תפעילו את AutcompleteActivity ישירות. במקום זאת, צריך להשתמש ב-Intent כדי להפעיל את Autocomplete (PlaceAutocomplete בספריית התאימות).

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

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

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

בדוגמה שלמטה נעשה שימוש ב-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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

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

      

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

איור 1: ווידג'ט של השלמה אוטומטית במצב OVERLAY

איור 2: ווידג'ט של השלמה אוטומטית במצב FULLSCREEN

רושמים קריאה חוזרת (callback) לתוצאת ה-intent.

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

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

      

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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

      

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

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

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

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

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

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

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

      

Java

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

      

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

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

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

      

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 שמוצגת בסוגי מקומות. ערכי האוסף מוגדרים על ידי הקבועים ב-PlaceTypes.

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

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

Kotlin

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

      

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

      

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

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

      

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

Kotlin

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

      

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .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.
• אם האפליקציה משתמשת בווידג'ט של ההשלמה האוטומטית, לא צריך לעשות שום דבר נוסף (השיוך הנדרש מוצג כברירת מחדל).
• אם אתם מאחזרים ומציגים מידע נוסף על מקום אחרי אחזור מקום לפי מזהה, אתם צריכים להציג גם את הייחוסים לצד שלישי.

לפרטים נוספים, קראו את המאמר בנושא שיוך (Attribution).

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

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

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

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

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

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

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

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

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

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

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

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

כן, צריך עוד פרטים

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

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

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

---

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

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

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

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

הטיית מיקום

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

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

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

הגבלת מיקום

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

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

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

פתרון בעיות

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

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