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 yer tahminleri döndürür. Kullanıcı yazdıkça otomatik tamamlama hizmeti işletmeler, adresler, artı kodları ve önemli yerler gibi yerler için ö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 girdiğinde widget, aralarından seçim yapabileceği tahmin edilen yerlerin bir listesini sunar. Kullanıcı bir seçim yaptığında, bir Place örneği döndürülür. Uygulamanız, seçilen yerle ilgili ayrıntıları almak için bu örneği kullanabilir.

Otomatik tamamlama widget'ını uygulamanıza eklemek için iki seçenek vardır:

1. Seçenek: Bir AutocompleteSupportFragment ekleme

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"
  />
  • Parçanın varsayılan olarak kenarlığı 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 yer döndürme işlemini gerçekleştirir. Aşağıdaki kod, parçaya 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.

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

  1. İstediğiniz Autocomplete modunu geçerek amaç oluşturmak için Autocomplete.IntentBuilder aracını kullanın.
  2. Amacı 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ısı registerForActivityResult tanımlayın.

Otomatik tamamlama amacı oluşturma

Aşağıdaki örnekte, otomatik tamamlama widget'ını amaç olarak başlatmak üzere bir amaç oluşturmak için Autocomplete.IntentBuilder kullanılmaktadı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üleme modlarından birini seçebilirsiniz. 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 modunda otomatik tamamlama widget'ı
Otomatik tamamlama widget&#39;ı tam ekran modunda görüntülendiğinde ekranın tamamını kaplar.
Şekil 2: TAM EKRAN modunda otomatik tamamlama widget'ı

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

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 bu tahmin, sonuç nesnesinde yer alan niyette sunulur. Amaç Autocomplete.IntentBuilder tarafından oluşturulduğundan Autocomplete.getPlaceFromIntent() yöntemi Place nesnesini bu nesneden çı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");
            }
        });

      

Yer tahminlerini programatik olarak alma

Otomatik tamamlama widget'ının sağladığı kullanıcı arayüzüne alternatif olarak özel bir arama kullanıcı arayüzü oluşturabilirsiniz. Bunun için uygulamanızın programatik olarak yer tahminleri alması gerekir. Uygulamanız, PlacesClient.findAutocompletePredictions() yöntemini çağırarak aşağıdaki parametrelere sahip bir FindAutocompletePredictionsRequest nesnesi ileterek 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 kullanıcı bir yer seçtiğinde sona erer.
  • Önerilen: Sonuçları belirtilen bölgeyle sınırlamak için enlem ve boylam sınırları belirten bir RectangularBounds nesnesi.
  • İsteğe bağlı: Sonuçların kısıtlanması gereken ülke veya ülkeleri belirten bir veya daha fazla iki harfli ülke kodu (ISO 3166-1-Alpha-2).
  • İ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ı açıklığa kavuşturmak için bu isteği kullanın.
    • TypeFilter.ADDRESS - Yalnızca tam adres içeren otomatik tamamlama sonuçlarını döndürür. Bu türü, kullanıcının tam olarak belirtilmiş bir adres aradığını biliyorsanız 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 LatLng. setOrigin() çağrısı yapıldığında hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen kaynaktan mesafeyi metre (distanceMeters) cinsinden döndürür.

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

Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() çağrısının tamamı 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 bir 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 yer için, yer ayrıntılarını almak amacıyla 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, açıklamanın aramayla eşleşen bölümlerini CharacterStyle kullanarak 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 kullanışlıdır. Örnekler: "Anatole France, Paris, France" 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ı, Place nesnesini daha sonra tekrar almak için kullanabilirsiniz. Android için Yerler SDK'sındaki yer kimlikleri hakkında daha fazla bilgi edinmek 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 metre cinsinden düz çizgi mesafesini 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 yapılabilir. 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 bir 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, ardından kullanıcı tarafından seçilen yere ilişkin Yer Ayrıntılarını almak için 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 en fazla beş ülkeye göre filtreleyebilirsiniz. Bu kısıtlamaları otomatik tamamlama etkinliğine, AutocompleteSupportFragment ve programatik otomatik tamamlama API'lerine uygulayabilirsiniz.

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

  • Tanımlanan bölge içindeki sonuçları tercih etmek için setLocationBias() yöntemini çağırı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() yöntemini çağırın (örneğin, TypeFilter.ADDRESS belirtilmesi yalnızca tam adres içeren sonuçları döndürür).
  • Yalnızca en fazla belirtilen beş ülkedeki sonuçları döndürmek için setCountries() numaralı telefonu arayın. Ülkeler iki karakterli, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.

Belirli bir bölgeyle ilgili yanlı sonuçlar

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre ayarlamak için RectangularBounds ileterek setLocationBias() çağrısı yapın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney şehrine göre ağırlıklandırmak 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ırlama

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle kısıtlamak için RectangularBounds ileterek setLocationRestriction() çağrısı yapın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney şehrine göre ayarlamak için parçalı örnekte setLocationRestriction() çağrısı 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 dayalı olarak döndürülebilir.

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

Otomatik tamamlama isteğinin sonuçlarını kısıtlayabilirsiniz. Böylece, bu sonuçlar yalnızca belirli bir yer türünü döndürür. Yer Türleri bölümünde 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 setTypesFilter() çağrısı yaparak filtreyi ayarlayın.

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

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

  • setTypesFilter() yöntemini çağırın ve Yer Türleri üzerinde gösterilen Tablo 3'ten bir tür koleksiyonu belirtin. Koleksiyon değerleri PlaceTypes'taki sabit değerlerle tanımlanır.

    İstekte 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 öğesinde 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ı yapılması 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 tam 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() numaralı telefonu 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() çağrısı 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 sayısı (QPD) ile 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ı). Aynı projenin kimlik bilgilerini kullanan tüm uygulamalar için istemci tarafı ve sunucu tarafı isteklerin toplamı olarak hesaplanır.

İlişkilendirmeleri uygulamanızda 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 herhangi bir ek işlem yapmanız gerekmez (varsayılan olarak gerekli ilişkilendirme gösterilir).
  • Kimliğe göre bir yer aldıktan sonra ek yer bilgileri alır ve görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.

Daha fazla bilgi için ilişkilendirmeler hakkındaki 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.

Bazı genel yönergeler şunlardır:

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

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Yer Tamamlama hizmetinin kullanım 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ında 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 Geocoding API sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığı takdirde, Coğrafi Kodlama API'si ile eşlenen İstek 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.

Başvurunuz, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerektiriyor mu?

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Uygulamanız; yer adı, iş durumu veya çalışma saatleri gibi Yer Ayrıntılarını gerektirdiğinden, Yer Otomatik Tamamlama özelliği, istekte bulunduğunuz yer verisi alanlarına bağlı olarak toplam 0, 017 ABD doları tutarında oturum başına ve geçerli Yer Verileri SKU'ları için bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak) kullanmalıdır.

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

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

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

Hayır, yalnızca adres ve konum gerekiyor

Coğrafi Kodlama API'si, Yer Otomatik Tamamlama performansınıza bağlı olarak, 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 ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların uygulanıp uygulanmadığına bağlı olarak değişiklik gösterir.

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 olarak dört veya daha az istekte otomatik yer tamamlama tahminini seçiyor mu?

Evet

Otomatik Tamamlama özelliğini, oturum jetonları olmadan programlı bir şekilde uygulayın ve seçilen yer tahmini için Coğrafi Kodlama API'sini çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Otomatik Yer Tamamlama - İstek Başına isteği oluşturmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, seçilen yer tahminiyle ilgili olarak dört isteğin ve bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olacaktır. Bu, oturum başına 0,017 ABD doları olan Oturum Başına Otomatik Tamamlama fiyatından düşük olacaktır.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ı ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Kullanıcılar bir Otomatik Yer Tamamlama tahminini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Yer Otomatik Tamamlama özelliği hem Yer Otomatik Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu (oturum başına toplam 0,017 ABD doları) kullanmalıdır.1

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

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

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

Yer Otomatik Tamamlama isteklerini geciktirmeyi düşünün
Bir Yer Otomatik Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejilerden yararlanarak uygulamanızın daha az istekte bulunmasını sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteklerinde bulunmak, kullanıcı yedi karakter yazıp ardından bir Coğrafi Kodlama API'sı isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 ABD Doları + 0,005 Coğrafi Kodlama ABD doları).1

Geciken istekler, ortalama programatik isteğinizi dörde dörde alabiliyorsa Geocoding API ile iyi performans gösteren Yer Otomatik Tamamlama uygulamasıyla ilgili 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 bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanmayı düşünün.


  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ği için dil tercihi gerekli değildir.
  • Otomatik Yer Tamamlama'ya bir harita eşlik ediyorsa, 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 Geocoding API'ye yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
    • Kullanıcının ada veya adrese göre belirli bir yer için sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuçlar bekleniyorsa konuma ağırlık vermeyi kullanın.
    Geocoding API'yi kullanmanın en iyi olduğu diğer senaryolar:
    • Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin tamamlanmadığı ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresi giren kullanıcılar. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
    • New York'ta "23-30 29

Sorun giderme

Çok çeşitli hatalar oluşsa da uygulamanızın karşılaşabileceği hataların büyük çoğunluğu genellikle yapılandırma hatalarından (örneğin, yanlış API anahtarı kullanılmış veya API anahtarı yanlış yapılandırılmıştır) veya 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.