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

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

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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

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

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

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

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

אפשרות 1: הטמעה של AutocompleteSupportFragment.
אפשרות 2: מתבססים על Intent כדי להפעיל את פעילות ההשלמה האוטומטית.

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

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

צריך להוסיף מקטע לפריסת ה-XML של הפעילות.
הוספת האזנה לפעילות או למקטע.

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

כדי להוסיף את 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, צריך לבצע את השלבים הבאים:

שימוש ב-Autocomplete.IntentBuilder כדי ליצור Intent, מעבירים את מצב Autocomplete הרצוי.
הגדרת מרכז האפליקציות לתוצאת פעילות 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.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);

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

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

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

רישום קריאה חוזרת (callback) לתוצאת Intent

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

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 שמכילה את הטקסט שהמשתמש הוקלד.
מומלץ: A AutocompleteSessionToken, שמקבץ את שלבי השאילתה והבחירה של החיפוש של המשתמש לצורכי חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, והיא תסתיים כשהם בוחרים מקום.
מומלץ: A RectangularBounds שמציין גבולות של קווי רוחב ואורך כדי להגביל תוצאות האזור שצוין.
אופציונלי: מדינה אחת או יותר בנות שתי אותיות קוד (ISO 3166-1 Alpha-2), שמציין את המדינה או המדינות שבהן התוצאות צריכות להיות מוגבלת.
אופציונלי: A 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) מחזירה את הטקסט המלא של תיאור המקום. זהו שילוב של טקסטים ראשיים ומשניים. דוגמה: "מגדל אייפל, שדרות רוטשילד, Paris, France". כמו כן, השיטה הזאת מאפשרת להדגיש את הקטעים שמתאים לחיפוש לסגנון שבחרתם, באמצעות CharacterStyle הפרמטר CharacterStyle הוא אופציונלי. יש להגדיר אותו כ-null צריך הדגשה.
getPrimaryText(CharacterStyle) מחזירה את הטקסט הראשי שמתאר מקום. בדרך כלל זה השם של במקום. דוגמאות: "מגדל אייפל" ו-"רחוב פיט 123".
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 מדינה שתואמת לאלפא-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() ומציינים אוסף סוגים מטבלה 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.
אם האפליקציה משתמשת בווידג'ט של ההשלמה האוטומטית, אין צורך בפעולה נוספת. (השיוך הנדרש מוצג כברירת מחדל).
אם מאחזרים ומציגים מידע נוסף על המקום אחרי שמקבלים מקום לפי ID, את/ה חייב להציג גם ייחוס של צד שלישי.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לא, דרושה רק כתובת ומיקום

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

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

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

כן

הטמעה של השלמה אוטומטית במקום באופן פרוגרמטי ללא אסימוני סשן וקריאה ל-Geocoding API בחיזוי המקום שנבחר.
Geocoding API מספק כתובות וקואורדינטות של קווי אורך ורוחב בסכום של $0.005 לכל בקשה. ניתן לבצע ארבע בקשות של השלמה אוטומטית במקום – לכל בקשה בעלות של 0.01,132$, כך שהעלות הכוללת של ארבע בקשות בנוסף לקריאת Geocoding API לגבי חיזוי המקום שנבחר תהיה 0.01632$. מחיר זה נמוך מהמחיר להשלמה אוטומטית לכל סשן בסך 0.017 $לכל סשן.¹

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

לא

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

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

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

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

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

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

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

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

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

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

פתרון בעיות

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

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