Place Autocomplete

Platform seçin: Android iOS JavaScript Web Hizmeti

Android için Yerler SDK'sındaki otomatik tamamlama hizmeti, kullanıcı arama sorgularına yanıt olarak tahminler döndürür. Kullanıcı yazdıkça otomatik tamamlama hizmeti işletmeler, adresler, artı kodları ve önemli yerler gibi yerlerle ilgili öneriler döndürür.

Otomatik tamamlamayı aşağıdaki yollarla uygulamanıza ekleyebilirsiniz:

Otomatik tamamlama widget'ı ekleme

Otomatik tamamlama widget'ı, yerleşik otomatik tamamlama işlevine sahip bir arama iletişim kutusudur. Kullanıcı arama terimleri girerken, widget'ta aralarından seçim yapabileceği tahmin edilen yerlerin listesi sunulur. Kullanıcı seçim yaptığında, uygulamanız seçilen yerle ilgili ayrıntıları almak için kullanabileceği bir Place örneği döndürülür.

Uygulamanıza otomatik tamamlama widget'ını eklemek için iki seçeneğiniz vardır:

1. Seçenek: Otomatik Tamamlama Destek Parçası Yerleştirme

Uygulamanıza AutocompleteSupportFragment eklemek için aşağıdaki adımları uygulayın:

  1. Etkinliğinizin XML düzenine bir parça ekleyin.
  2. Etkinliğinize veya parçanıza dinleyici ekleyin.

Bir etkinliğe AutocompleteSupportFragment ekleme

Bir etkinliğe AutocompleteSupportFragment eklemek için XML düzenine yeni bir parça ekleyin. Örneğin:

<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"
  />
  • Varsayılan olarak parçada kenarlık veya arka plan yoktur. Tutarlı bir görsel görünüm sağlamak için parçayı CardView gibi başka bir düzen öğesinin içine yerleştirin.
  • Otomatik tamamlama parçasını kullanıyorsanız ve onActivityResult öğesini geçersiz kılmanız gerekiyorsa super.onActivityResult yöntemini çağırmanız gerekir. Aksi takdirde parça düzgün çalışmaz.

Etkinliğe PlaceSelectionListener ekleme

PlaceSelectionListener, kullanıcının seçimine yanıt olarak bir yer döndürmeyi işler. Aşağıdaki kod, parçaya bir referans oluşturmayı ve AutocompleteSupportFragment öğenize işleyici eklemeyi göstermektedir:

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. Seçenek: Otomatik tamamlama etkinliğini başlatmak için intent kullanma

Uygulamanızın farklı bir gezinme akışı kullanmasını istiyorsanız (örneğin, otomatik tamamlama deneyimini arama alanından değil bir simgeden tetiklemek için) uygulamanız bir amaç kullanarak otomatik tamamlamayı başlatabilir.

Intent kullanarak otomatik tamamlama widget'ını başlatmak için aşağıdaki adımları uygulayın:

  1. İstenen Autocomplete modunu kullanarak amaç oluşturmak için Autocomplete.IntentBuilder aracını kullanın.
  2. Niyeti başlatmak ve sonuçta kullanıcının seçtiği yer tahminini işlemek için kullanılabilecek bir etkinlik sonucu başlatıcı registerForActivityResult tanımlayın.

Otomatik tamamlama amacı oluşturma

Aşağıdaki örnekte, otomatik tamamlama widget'ını intent olarak başlatmak üzere bir intent oluşturmak için Autocomplete.IntentBuilder kullanılmıştır:

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

      

Otomatik tamamlama widget'ını başlatmak için bir intent kullanırken yer paylaşımlı veya tam ekran görüntü modları arasından seçim yapabilirsiniz. Aşağıdaki ekran görüntülerinde sırasıyla her bir görüntüleme modu gösterilmektedir:

Yer paylaşımı modunda görüntülendiğinde, otomatik tamamlama widget&#39;ı çağrı kullanıcı arayüzünün üzerine yerleştirilmiş olarak görünür.
Şekil 1: OVERLAY modundaki otomatik tamamlama widget'ı
Otomatik tamamlama widget&#39;ı tam ekran modunda görüntülendiğinde tüm ekranı kaplar.
Şekil 2: TAM EKRAN modunda otomatik tamamlama widget'ı

Amaç sonucu için bir geri çağırma kaydet

Kullanıcı bir yer seçtiğinde bildirim almak için etkinliği başlatan ve sonucu aşağıdaki örnekte gösterildiği gibi işleyen bir registerForActivityResult() başlatıcı tanımlayın. Kullanıcı bir tahmin seçtiyse tahmin, sonuç nesnesinde bulunan amaçta sunulur. Amaç Autocomplete.IntentBuilder tarafından oluşturulduğundan Autocomplete.getPlaceFromIntent() yöntemi, Place nesnesini bundan çıkarabilir.

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

      

Programlı bir şekilde yer tahminlerini alma

Otomatik tamamlama widget'ı tarafından sağlanan kullanıcı arayüzüne alternatif olarak özel arama kullanıcı arayüzü oluşturabilirsiniz. Bunun için uygulamanızın yer tahminlerini programatik olarak alması gerekir. Uygulamanız, aşağıdaki parametrelere sahip bir FindAutocompletePredictionsRequest nesnesi ileterek PlacesClient.findAutocompletePredictions() yöntemini çağırarak otomatik tamamlama API'sinden tahmin edilen yer adları ve/veya adreslerin bir listesini alabilir:

  • Zorunlu: Kullanıcı tarafından yazılan metni içeren bir query dizesi.
  • Önerilen: Kullanıcı aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandıran bir AutocompleteSessionToken. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer.
  • Önerilen: Sonuçları belirtilen bölgeyle sınırlamak için enlem ve boylam sınırlarını belirten bir RectangularBounds nesnesi.
  • İsteğe bağlı: Sonuçların kısıtlanması gereken ülkeyi veya ülkeleri belirten bir veya daha fazla iki harfli ülke kodu (ISO 3166-1 Alpha-2) içerir.
  • İsteğe bağlı: Sonuçları belirtilen yer türüyle kısıtlamak için kullanabileceğiniz bir TypeFilter. Aşağıdaki yer türleri desteklenir:

    • TypeFilter.GEOCODE – İşletmeler yerine yalnızca coğrafi kodlama sonuçlarını döndürür. Belirtilen konumun belirsiz olabileceği sonuçları netleştirmek için bu isteği kullanın.
    • TypeFilter.ADDRESS - Yalnızca kesin adres içeren otomatik tamamlama sonuçlarını döndürür. Kullanıcının tam olarak belirtilen bir adresi aradığını biliyorsanız bu türü kullanın.
    • TypeFilter.ESTABLISHMENT – Yalnızca işletme olan yerleri döndürür.
    • TypeFilter.REGIONS – Yalnızca aşağıdaki türlerden biriyle eşleşen yerleri döndürür:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES – Yalnızca LOCALITY veya ADMINISTRATIVE_AREA_LEVEL_3 ile eşleşen sonuçları döndürür.

  • İsteğe bağlı: İsteğin kaynak konumunu belirten bir LatLng. setOrigin() yöntemini çağırdığınızda hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen kaynaktan metre (distanceMeters) cinsinden mesafeyi döndürür.

Yer türleri hakkında bilgi için yer türleri rehberine bakın.

Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() için yapılan tam bir çağrı gösterilmektedir.

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, Task içinde FindAutocompletePredictionsResponse döndürür. FindAutocompletePredictionsResponse, tahmin edilen yerleri temsil eden AutocompletePrediction nesnelerinin bir listesini içerir. Sorguya ve filtre ölçütlerine karşılık gelen bilinen bir yer yoksa liste boş olabilir.

Tahmin edilen her bir yerle ilgili olarak, yer ayrıntılarını almak için aşağıdaki yöntemleri çağırabilirsiniz:

  • getFullText(CharacterStyle), bir yer açıklamasının tam metnini döndürür. Bu, birincil ve ikincil metnin bir kombinasyonudur. Örnek: "Eyfel Kulesi, Avenue Anatole France, Paris, Fransa". Ayrıca bu yöntem, CharacterStyle kullanarak açıklamanın aramayla eşleşen bölümlerini istediğiniz bir stille vurgulamanıza olanak tanır. CharacterStyle parametresi isteğe bağlıdır. Vurgulamaya ihtiyacınız yoksa null değerine ayarlayın.
  • getPrimaryText(CharacterStyle), bir yeri açıklayan ana metni döndürür. Bu genellikle yerin adıdır. Örnekler: "Eyfel Kulesi" ve "123 Pitt Street".
  • getSecondaryText(CharacterStyle), bir yer açıklamasının yan kuruluş metnini döndürür. Bu, örneğin otomatik tamamlama tahminlerini gösterirken ikinci satır olarak yararlıdır. Örnekler: "Anatole France, Paris, Fransa" ve "Sidney, Yeni Güney Galler".
  • getPlaceId(), tahmin edilen yerin yer kimliğini döndürür. Yer kimliği, bir yeri benzersiz şekilde tanımlayan metinsel bir tanımlayıcıdır. Bu tanımlayıcıyı daha sonra Place nesnesini almak için kullanabilirsiniz. Android için Yerler SDK'sındaki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları bölümüne bakın. Yer kimlikleri hakkında genel bilgi için Yer kimliğine genel bakış konusuna bakın.
  • getPlaceTypes(), bu yerle ilişkili yer türlerinin listesini döndürür.
  • getDistanceMeters(), bu yer ile istekte belirtilen kaynak arasındaki düz çizgi mesafesini metre cinsinden döndürür.

Oturum jetonları

Oturum jetonları, bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından tek bir yer seçimi olabilir. Bir oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanızın her oturum için yeni bir jeton oluşturması gerekir. Tüm programatik otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz (bir parçayı yerleştirdiğinizde veya amaç kullanarak otomatik tamamlamayı başlattığınızda API bunu otomatik olarak halleder).

Android için Yerler SDK'sı her oturumu tanımlamak için bir AutocompleteSessionToken kullanır. Uygulamanız her yeni oturum başladığında yeni bir oturum jetonu iletmeli ve ardından, kullanıcı tarafından seçilen yer için Yer Ayrıntılarını almak üzere bir sonraki fetchPlace() çağrısında yer kimliğiyle birlikte aynı jetonu iletmelidir.

Oturum jetonları hakkında daha fazla bilgi edinin.

Otomatik tamamlama sonuçlarını sınırla

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle sınırlandırabilir ve/veya sonuçları bir ya da daha fazla yer türüne veya beş ülkeye göre filtreleyebilirsiniz. Bu kısıtlamaları otomatik tamamlama etkinliğine, AutocompleteSupportFragment ve programatik otomatik tamamlama API'lerine uygulayabilirsiniz.

Sonuçları kısıtlamak için aşağıdakileri yapın:

  • Tanımlı bölge içindeki sonuçları tercih etmek için setLocationBias() çağrısı yapın (tanımlanan bölgenin dışından bazı sonuçlar yine de döndürülebilir).
  • Yalnızca tanımlanan bölgedeki sonuçları göstermek için setLocationRestriction() yöntemini çağırın (yalnızca tanımlanan bölgedeki sonuçlar döndürülür).
  • Yalnızca belirli bir yer türüne uygun sonuçları döndürmek için setTypesFilter() numaralı telefonu arayın (örneğin, TypeFilter.ADDRESS belirtilmesi yalnızca tam adrese sahip sonuçları döndürür).
  • Yalnızca belirtilen en fazla beş ülkedeki sonuçları döndürmek için setCountries() numaralı telefonu arayın. Ülkeler iki karakterden oluşan bir ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.

Belirli bir bölgeyle ilgili yanlılık sonuçları

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre ayarlamak için RectangularBounds ileterek setLocationBias() yöntemini çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine ağırlık vermek için parça örneğinde setLocationBias() çağrısı gösterilmektedir.

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

      

Sonuçları belirli bir bölgeyle sınırlandırma

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle kısıtlamak için RectangularBounds ileterek setLocationRestriction() yöntemini çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine ağırlık vermek için parça örneğinde setLocationRestriction() çağrısının yapılması gösterilmektedir.

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

      

Not: Bu kısıtlama yalnızca rotaların tamamına uygulanır. Dikdörtgen sınırların dışında kalan sentetik sonuçlar, konum kısıtlamasıyla çakışan bir rotaya bağlı olarak döndürülebilir.

Sonuçları yer türlerine veya koleksiyon türüne göre filtreleyin

Otomatik tamamlama isteğindeki sonuçları, yalnızca belirli bir yer türünü döndürmeleri için kısıtlayabilirsiniz. Yer Türleri sayfasındaki Tablo 1, 2 ve 3'te listelenen yer türlerini veya bir tür koleksiyonunu kullanarak bir filtre belirtin. Hiçbir şey belirtilmezse tüm türler döndürülür.

Otomatik tamamlama sonuçlarını filtrelemek için filtreyi ayarlamak üzere setTypesFilter() çağrısı yapın.

Tür belirtmek veya koleksiyon filtresi türü için:

  • setTypesFilter() öğesini çağırın ve Yer Türleri üzerinde gösterilen Tablo 1 ve Tablo 2'den en fazla beş type değeri belirtin. Tür değerleri, PlaceTypes'taki sabit değerlerle tanımlanır.

  • setTypesFilter() işlevini çağırın ve Yer Türleri bölümünde gösterilen Tablo 3'ten bir tür koleksiyonu belirtin. Koleksiyon değerleri PlaceTypes'taki sabit değerlerle tanımlanır.

    İstekte yalnızca Tablo 3'teki tek bir türe izin verilir. Tablo 3'ten bir değer belirtirseniz Tablo 1 veya Tablo 2'den bir değer belirtemezsiniz. Bunu yaparsanız bir hata oluşur.

Aşağıdaki kod örneği, AutocompleteSupportFragment üzerinde setTypesFilter() işlevini çağırır ve birden çok tür değeri belirtir.

Kotlin



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

      

Java


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

      

Aşağıdaki kod örneğinde, bir tür koleksiyonu belirterek yalnızca kesin adrese sahip sonuçlar döndüren bir filtre ayarlamak için AutocompleteSupportFragment üzerinde setTypesFilter() çağrısının gösterilmektedir.

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


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

      

Aşağıdaki kod örneğinde, bir tür koleksiyonu belirterek yalnızca kesin adresli sonuçları döndüren bir filtre ayarlamak için IntentBuilder üzerinde setTypesFilter() çağrısı gösterilmektedir.

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

      

Sonuçları ülkeye göre filtrele

Otomatik tamamlama sonuçlarını beş ülkeye kadar filtrelemek için ülke kodunu ayarlamak üzere setCountries() numarasını arayın. Ardından, filtreyi bir parçaya veya amaca iletin. Ülkeler iki karakterli, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.

Aşağıdaki kod örneğinde, yalnızca belirtilen ülkelerdeki sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment üzerinde setCountries() işlevinin çağrılması gösterilmektedir.

Kotlin



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

      

Java


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

      

Kullanım sınırları

Android için Yerler SDK'sı da dahil olmak üzere Places API kullanımınız artık günlük maksimum istek (QPD) sayısıyla sınırlı değildir. Ancak aşağıdaki kullanım sınırları geçerliliğini korur:

  • Hız sınırı 6.000 QPM'dir (dakika başına istek sayısı). Bu değer, aynı projenin kimlik bilgilerini kullanan tüm uygulamalar için istemci taraflı ve sunucu tarafı isteklerin toplamı olarak hesaplanır.

Uygulamanızda ilişkilendirmeleri gösterin

  • Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüz "Powered by Google" ilişkilendirmesi görüntülemeli veya Google markalı bir haritada görünmelidir.
  • Uygulamanız otomatik tamamlama widget'ını kullanıyorsa başka bir işlem yapmanız gerekmez (gerekli ilişkilendirme varsayılan olarak gösterilir).
  • Kimliğe göre yer aldıktan sonra ek yer bilgilerini alır ve görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.

Daha fazla bilgi için atıflar ile ilgili belgeleri inceleyin.

Otomatik Yer Tamamlama optimizasyonu

Bu bölümde Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.

Aşağıda bazı genel yönergeler verilmiştir:

  • Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu Maps JavaScript API Otomatik Tamamlama widget'ı, Android için Yerler SDK'sı Otomatik Tamamlama widget'ı veya iOS için Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü kullanmaktır
  • Otomatik Yerleştirme özelliğinin temel veri alanlarını daha baştan anlayın.
  • Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
  • API'nin hata döndürdüğü durumlarda uygulamanızın sorunsuz bir şekilde bozulması için hata işlemeyi kullanın.
  • Uygulamanızın hiçbir seçim olmadığında işlem yaptığından ve kullanıcılara devam etmek için bir yol sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Yer Tamamlama hizmetini kullanma maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larındaki alan maskelerini kullanın.

Gelişmiş maliyet optimizasyonu

İstek Başına fiyatlandırmaya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'si sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik olarak uygulanmasını deneyin. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen istek başına fiyatlandırma, oturum başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

  • Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntıları çağrısından daha az için sunar.
  • Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
İhtiyaçlarınıza uygun Otomatik Yer Tamamlama uygulamasını seçme konusunda yardım için aşağıdaki soruya verdiğiniz yanıta uygun sekmeyi seçin.

Uygulamanızda, seçilen tahminin adresi ve enlemi/boylamı dışında herhangi bir bilgi gerekiyor mu?

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntılarıyla otomatik yer tamamlama özelliğini oturuma dayalı olarak kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gibi yer ayrıntıları gerektirdiğinden Otomatik Yer Tamamlama özelliğinin uygulamanızda, istekte bulunduğunuz yer verisi alanlarına bağlı olarak toplam 0, 017 ABD doları tutarında oturum başına 0, 017 ABD doları tutarında bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik) ile birlikte geçerli Yer Verileri SKU'ları kullanılmalıdır}{/14

Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Seçilen tahminle ilgili hem Otomatik Yer Tamamlama istekleri hem de Yer Ayrıntısı isteği buna dahildir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Otomatik Yer Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtındaki yer kimliği
  2. Otomatik Yerleştirme isteğinde kullanılan oturum jetonu
  3. İhtiyacınız olan yer verisi alanlarını belirten fields parametresi

Hayır, yalnızca adres ve konum gerekiyor

Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak, Coğrafi Kodlama API'si, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Otomatik Tamamlama verimliliği, kullanıcıların girdiği girişlere, uygulamanın kullanıldığı yere ve performans optimizasyonu en iyi uygulamalarının uygulanıp uygulanmadığına bağlı olarak değişir.

Aşağıdaki soruyu yanıtlamak için bir kullanıcının, uygulamanızda Otomatik Yer Tamamlama tahmini seçmeden önce ortalama kaç karakter girdiğini analiz edin.

Kullanıcılarınız ortalama dört veya daha az istekte Otomatik Yer Tamamlama tahminini seçiyor mu?

Evet

Otomatik Tamamlama özelliğini oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Coğrafi Kodlama API'sini çağırın.
GeoCode API, istek başına 0,005 ABD doları karşılığında adresleri ve enlem/boylam koordinatlarını sağlar. Dört Otomatik Tamamlama - İstek Başına isteği yapmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, dört isteğin ve seçilen yer tahminiyle ilgili bir GeoCode API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu, oturum başına 0,017 ABD doları tutarındaki Oturum Başına Otomatik Tamamlama fiyatından düşük olur.1

Kullanıcılarınızın aradıkları tahmini daha da az karakterle elde etmelerine yardımcı olmak için performans en iyi uygulamalarından yararlanabilirsiniz.

Hayır

Yer Ayrıntılarıyla otomatik yer tamamlama özelliğini oturuma dayalı olarak kullanın.
Bir kullanıcı Otomatik Yer Tamamlama tahminini seçmeden önce yapmasını beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama istekleriniz hem Yer Otomatik Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanmalıdır.Bu durumda toplam maliyet oturum başına 0,017 ABD dolarıdır.1

Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Seçilen tahminle ilgili hem Otomatik Yer Tamamlama istekleri hem de Yer Ayrıntısı isteği buna dahildir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Otomatik Yer Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtındaki yer kimliği
  2. Otomatik Yerleştirme isteğinde kullanılan oturum jetonu
  3. Adres ve geometri gibi Temel Veriler alanlarını belirten fields parametresi

Otomatik Yer Tamamlama isteklerini ertelemeyi değerlendirin
Otomatik Yer Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejiler benimseyerek uygulamanızın daha az istek yapmasını sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Yer Tamamlama isteğinde bulunmak, kullanıcı yedi karakter girdikten sonra bir Coğrafi Kodlama API isteği yaptığınız bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 ABD Doları Otomatik Tamamlama + 0,005 ABD Doları Coğrafi Kodlama).1

Geciken istekler, ortalama programatik isteğinizi dörde dörde düşürebilirse Coğrafi Kodlama API'siyle yüksek performans gösteren Otomatik Yer Tamamlama uygulaması için yönergeleri izleyebilirsiniz. Geciken isteklerin, her yeni tuş vuruşunda tahmin görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha az karakterle elde etmelerine yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.


  1. Burada listelenen maliyetler ABD doları cinsindendir. Tam fiyatlandırma bilgileri için lütfen Google Haritalar Platformu Faturalandırması sayfasına bakın.

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansını optimize etme yöntemleri açıklanmaktadır:

  • Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, yere ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtiğinden widget'larda dil tercihi gerekmez.
  • Otomatik Yer Tamamlama bir haritayla birlikte veriliyorsa, konumu harita görünümüne göre yönlendirebilirsiniz.
  • Kullanıcının otomatik tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerin hiçbiri istenen sonuç adresi olmadığından daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
    • Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız GeoKodlama API'sine yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
    • Kullanıcının belirli bir yerle ilgili sorguları ada veya adrese göre girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
    Coğrafi Kodlama API'sini kullanmaya devam etmek için en iyi seçenek diğer senaryolar:
    • Alt kuruluş adresleri için Otomatik Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt kuruluş adresleri giren kullanıcılar. Örneğin, Çekçe adres olan "Stroupežnického 3191/17, Praha", Otomatik Yer Tamamlama'da kısmi bir tahmin verir.
    • New York City'de "23-30 29th St, Queens" gibi yol segmenti ön ekleriyle veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti önekleriyle adres giren kullanıcılar.

Sorun giderme

Çok çeşitli hatalar meydana gelse de uygulamanızın karşılaşabileceği hataların çoğu genellikle yapılandırma hatalarından (örneğin, yanlış API anahtarı kullanılmış veya API anahtarı yanlış yapılandırılmıştır) ya da kota hatalarından (uygulamanız kotasını aştı) kaynaklanır. Kotalar hakkında daha fazla bilgi için Kullanım Sınırları bölümüne bakın.

Otomatik tamamlama kontrolleri kullanılırken ortaya çıkan hatalar onActivityResult() geri çağırmasında döndürülür. Sonucun durum mesajını almak için Autocomplete.getStatus() numaralı telefonu arayın.