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

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

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

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

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

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

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

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

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

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

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

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

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

הוספת השלמה אוטומטיתSupportFragment לפעילות

כדי להוסיף את 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 מטפל בהחזרת מקום בתגובה לבחירת המשתמש. הקוד הבא מציג איך ליצור הפניה למקטע ולהוסיף event listener ל-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);

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

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

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

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

אסימוני סשן

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

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

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

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

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

כדי להגביל את התוצאות, יש לבצע את הפעולות הבאות:

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

מידע נוסף זמין במסמכי התיעוד בנושא שיוך (Attribution).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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