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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin



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

Java


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

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

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

Kotlin



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

Java


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

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

סינון התוצאות לפי סוגי מקומות או לפי אוסף

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

כדי לסנן תוצאות של השלמה אוטומטית, קוראים לפונקציה setTypesFilter() כדי להגדיר את המסנן.

כדי לציין מסנן לאוסף לפי סוג או סוג:

קוראים לפונקציה setTypesFilter() ומציינים עד חמישה ערכים של type מטבלה 1 ומטבלה 2 שמוצגים בקטע Place types (סוגי מקום). ערכי הסוגים מוגדרים על ידי הקבועים ב-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 (בקשות לדקה). הוא מחושב כסכום של הבקשות בצד הלקוח ובצד השרת לכל האפליקציות שמשתמשות בפרטי הכניסה של אותו פרויקט.

הצגת ייחוס באפליקציה

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

מידע נוסף זמין במאמר שיוכים.

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

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

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

הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט ההשלמה האוטומטית של 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 $לכל סשן.¹

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

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

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

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

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

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

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

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

פתרון בעיות

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

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