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ı yazarken otomatik tamamlama hizmeti; işletme, adres, artı kodu ve önemli yerler gibi yerlerle ilgili öneriler döndürür.

Uygulamanıza otomatik tamamlama özelliğini aşağıdaki yöntemlerle ekleyebilirsiniz:

Otomatik tamamlama widget'ı ekleme

Otomatik tamamlama widget'ı, yerleşik otomatik tamamlama işlevine sahip bir arama iletişim kutusudur. Kullanıcı arama terimlerini girerken widget, aralarından seçim yapılabilecek tahmini yerlerin listesini gösterir. 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: AutocompleteSupportFragment öğesini yerleştirme

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

  1. Etkinliğinizin XML düzenine bir fragman ekleyin.
  2. Etkinliğinize veya parçanıza bir 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ık veya arka planı yoktur. Tutarlı bir görsel görünüm sağlamak için fragmanı CardView gibi başka bir düzen öğesinin içine yerleştirin.
  • Otomatik tamamlama fragmanını kullanıyorsanız ve onActivityResult değerini geçersiz kılmanız gerekiyorsa super.onActivityResult işlevini çağırmanız gerekir. Aksi takdirde, fragman düzgün çalışmaz.

Bir etkinliğe PlaceSelectionListener ekleme

PlaceSelectionListener, kullanıcının seçimine yanıt olarak bir yer döndürür. Aşağıdaki kodda, parçaya referans oluşturma ve AutocompleteSupportFragment öğenize dinleyici ekleme gösterilmektedir:

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 kullanın

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

Otomatik tamamlama widget'ını bir intent kullanarak başlatmak için aşağıdaki adımları uygulayın:

  1. İstediğiniz Autocomplete modunu ileterek bir intent oluşturmak için Autocomplete.IntentBuilder işlevini kullanın.
  2. Amacın başlatılması ve sonuçta kullanıcının seçtiği yer tahmininin işlenmesi için kullanılabilecek bir etkinlik sonucu başlatıcısı registerForActivityResult tanımlayın.

Otomatik tamamlama intent'i oluşturma

Aşağıdaki örnekte, otomatik tamamlama widget'ını intent olarak başlatmak 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şımı veya tam ekran görüntüleme modları arasından seçim yapabilirsiniz. Aşağıdaki ekran görüntülerinde her bir görüntüleme modu sırasıyla gösterilmektedir:

Otomatik tamamlama widget&#39;ı, yer paylaşımı modunda görüntülendiğinde arayan kullanıcı arayüzünün üzerine yerleştirilir.
Şekil 1: ÜST BİÇİM modunda otomatik tamamlama widget'ı
Otomatik tamamlama widget&#39;ı, tam ekran modunda gösterildiğinde ekranın tamamını doldurur.
Şekil 2: TAM EKRAN modunda otomatik tamamlama widget'ı

Intent sonucu için geri arama kaydetme

Kullanıcı bir yer seçtiğinde bildirim almak için aşağıdaki örnekte gösterildiği gibi etkinliği başlatan ve sonucu işleyen bir registerForActivityResult() başlatıcı tanımlayın. Kullanıcı bir tahmin seçtiyse bu tahmin, sonuç nesnesinde bulunan intent'te yayınlanır. Intent, Autocomplete.IntentBuilder tarafından oluşturulduğundan Autocomplete.getPlaceFromIntent() yöntemi, Place nesnesini buradan ayıklayabilir.

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'ı tarafından sağlanan kullanıcı arayüzüne alternatif olarak özel bir arama kullanıcı arayüzü oluşturabilirsiniz. Bunun için uygulamanızın yer tahminlerini programatik olarak alması gerekir. Uygulamanız, PlacesClient.findAutocompletePredictions() işlevini çağırarak ve aşağıdaki parametreleri içeren bir FindAutocompletePredictionsRequest nesnesi ileterek otomatik tamamlama API'sinden tahmin edilen yer adlarının ve/veya adreslerin listesini alabilir:

  • Zorunlu: Kullanıcının yazdığı metni içeren bir query dizesi.
  • Önerilen: Bir kullanıcı aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandıran 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).

  • İsteğe bağlı: Sonuçları belirtilen yer türüyle sınırlamak için kullanabileceğiniz bir TypeFilter. Aşağıdaki yer türleri desteklenir:

    • TypeFilter.GEOCODE: İşletme yerine yalnızca coğrafi kodlama sonuçlarını döndürür. Belirtilen konumun belirsiz olabileceği sonuçlarda anlam karışıklığını gidermek için bu isteği kullanın.
    • TypeFilter.ADDRESS: Yalnızca tam adres içeren otomatik tamamlama sonuçlarını döndürür. Kullanıcının tam olarak belirtilen bir adres 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() işlevini çağırdığınızda hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen başlangıç noktasına olan mesafeyi metre cinsinden (distanceMeters) döndürür.

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

Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() işlevine 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 bir FindAutocompletePredictionsResponse döndürür. FindAutocompletePredictionsResponse, öngörülen yerleri temsil eden AutocompletePrediction nesnelerinin listesini içerir. Sorguya ve filtre ölçütlerine karşılık gelen bilinen bir yer yoksa liste boş olabilir.

Tahmin edilen her yer için yer ayrıntılarını almak üzere 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 birleşimidir. Örnek: "Eyfel Kulesi, Anatole France Caddesi, 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 olarak 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 Caddesi".
  • getSecondaryText(CharacterStyle) bir yer açıklamasının yan metnini döndürür. Bu, örneğin, otomatik tamamlama tahminlerini gösterirken ikinci bir satır olarak kullanışlıdır. Örnekler: "Avenue Anatole France, Paris, Fransa" ve "Sydney, New South Wales".
  • getPlaceId() tahmin edilen yerin yer kimliğini döndürür. Yer kimliği, bir yeri benzersiz şekilde tanımlayan metin tabanlı bir tanımlayıcıdır. Bu kimliği, Placeöğesini daha sonra tekrar almak için kullanabilirsiniz. Android için Yerler SDK'sındaki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları başlıklı makaleyi inceleyin. Yer kimlikleri hakkında genel bilgi için Yer kimliğine genel bakış başlıklı makaleyi inceleyin.
  • getPlaceTypes() bu yerle ilişkili yer türlerinin listesini döndürür.
  • getDistanceMeters(), bu yer ile istekte belirtilen başlangıç noktası arasındaki doğrusal mesafeyi metre cinsinden döndürür.

Oturum jetonları

Oturum jetonları, 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 bir yer seçimi olabilir. Bir oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm programatik otomatik tamamlama oturumları için oturum jetonlarını kullanmanızı öneririz (Bir parçayı yerleştirdiğinizde veya bir intent kullanarak otomatik tamamlamayı başlattığınızda API bu işlemi otomatik olarak gerçekleştirir).

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

Oturum jetonları hakkında daha fazla bilgi edinin.

Otomatik tamamlama sonuçlarını kısıtlama

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle sınırlandırabilir ve/veya sonuçları bir veya daha fazla yer türüne ya da 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ı kısıtlamak için aşağıdakileri yapın:

  • Tanımlanmış bölgedeki sonuçları tercih etmek için setLocationBias() işlevini çağırın (tanımlanmış bölgenin dışındaki bazı sonuçlar yine de döndürülebilir).
  • Tanımlanmış bölgedeki sonuçları yalnızca göstermek için setLocationRestriction() işlevini çağırın (yalnızca tanımlanmış 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() işlevini çağırın (örneğin, TypeFilter.ADDRESS belirtildiğinde yalnızca tam adresi olan sonuçlar döndürülür).
  • Yalnızca belirtilen beş ülke içindeki sonuçları döndürmek için setCountries() numaralı telefonu arayın. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir.

Sonuçları belirli bir bölgeye göre yönlendirme

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye yönlendirmek için RectangularBounds parametresini göndererek setLocationBias() işlevini çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine yönlendirmek için bir fragment ö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 parametresini göndererek setLocationRestriction() işlevini çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesindeki bir bölgeye yönlendirmek için bir fragment örneğinde 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ı için uygulanır. Dikdörtgen sınırların dışında bulunan sentetik sonuçlar, konum kısıtlamasıyla örtüşen bir rotaya göre döndürülebilir.

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

Otomatik tamamlama isteğinde bulunan sonuçları yalnızca belirli bir yer türü döndürecek şekilde kısıtlayabilirsiniz. Yer Türleri bölümündeki Tablo 1, 2 ve 3'te listelenen yer türlerini veya 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() düğmesine basın.

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

  • setTypesFilter() işlevini çağırın ve Yer Türleri bölümünde gösterilen Tablo 1 ile Tablo 2'den en fazla beş tür değeri belirtin. Tür değerleri, PlaceTypes'taki sabitler tarafından 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 sabitler tarafından 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. Aksi takdirde hata meydana gelir.

Aşağıdaki kod örneğinde, bir AutocompleteSupportFragment üzerinde setTypesFilter() çağrılıyor ve birden fazla tür değeri belirtiliyor.

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 tam adres içeren sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment üzerinde setTypesFilter() çağrısı 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 adres içeren 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 filtreleme

Otomatik tamamlama sonuçlarını en fazla beş ülkeyle filtrelemek için ülke kodunu ayarlamak üzere setCountries() düğmesini tıklayın. Ardından filtreyi bir parçaya veya amaca iletin. Ülkeler, iki karakterli, ISO 3166-1 Alpha-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 bir 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 Yerler API'sini kullanımınız artık günlük maksimum istek sayısıyla (QPD) sınırlı değildir. Ancak aşağıdaki kullanım sınırları geçerli olmaya devam eder:

  • Hız sınırı 6.000 QPM'dir (dakikada istek). Aynı projenin kimlik bilgilerini kullanan tüm uygulamalar için istemci tarafı ve sunucu tarafı isteklerinin toplamı olarak hesaplanır.

Uygulamanızda ilişkilendirmeleri gösterme

  • Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüzde "Google Tarafından Güçlendirilmiştir" atfı gösterilmeli veya Google markalı bir haritada görünmelidir.
  • Uygulamanızda otomatik tamamlama widget'ı kullanılıyorsa ek bir işlem yapmanız gerekmez (gerekli ilişkilendirme varsayılan olarak gösterilir).
  • No ile yer aldıktan sonra ek yer bilgileri alır ve gösterirseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.

Daha fazla bilgi için ilişkilendirmeler ile ilgili dokümanları inceleyin.

Yer adı otomatik tamamlama optimizasyonu

Bu bölümde, yer otomatik 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'ını, Android için Yerler SDK'sı otomatik tamamlama widget'ını veya iOS için Yerler SDK'sı otomatik tamamlama kullanıcı arayüzü denetimini kullanmaktır.
  • Yer Otomatik Tamamlama için temel veri alanlarını baştan itibaren öğrenin.
  • Konum önyargısı ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
  • API hata döndürdüğünde uygulamanızın sorunsuz bir şekilde işlevini yitirmesini sağlamak için hata işleme özelliğini kullanın.
  • Uygulamanızın, seçim yapılmadığında kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Yer Otomatik Tamamlama hizmetini kullanmanın maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek amacıyla 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 sonuçlarını istemek için Otomatik Yer Tamamlama'nın programatik olarak uygulanmasını değerlendirin. Geocoding API ile birlikte kullanılan istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılanıyorsa oturum başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

  • Kullanıcının seçtiği yerin yalnızca enlem/boylamına veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri bir Yer Ayrıntıları çağrısından daha kısa sürede sağlar.
  • Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmini isteği içinde 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 yer otomatik tamamlama uygulamasını seçmenize yardımcı olması için aşağıdaki soruya verdiğiniz yanıta karşılık gelen sekmeyi seçin.

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

Evet, daha fazla ayrıntı gerekiyor

Oturum tabanlı yer otomatik tamamlamayı Yer Ayrıntıları ile kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi yer ayrıntılarını gerektirdiğinden, Yer Otomatik Tamamlama uygulamanızda bir oturum jetonu (programlı olarak veya JavaScript, Android ya da iOS widget'larına yerleştirilmiş olarak) kullanılmalıdır.Bu durumda, oturum başına 0, 017 ABD doları ve istediğiniz yer verileri alanlarına bağlı olarak geçerli Yerler Verileri SKU'ları için toplam maliyet oluşur.1

Widget uygulama
Oturum yönetimi, JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Buna hem yer otomatik tamamlama istekleri hem de seçili tahmindeki yer ayrıntıları isteği dahildir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields parametresini belirtmeyi unutmayın.

Programlı uygulama
Yer Otomatik Tamamlama isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları'nı talep ederken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtındaki yer kimliği
  2. Yer Otomatik Tamamlama 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 bilgisi gerekir.

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

Aşağıdaki soruyu yanıtlamak için uygulamanızda bir yer otomatik tamamlama tahmini seçmeden önce kullanıcının ortalama olarak kaç karakter yazdığını analiz edin.

Kullanıcılar, ortalama dört veya daha az istekte bir Yer Otomatik Tamamlama tahmini seçiyor mu?

Evet

Oturum jetonları olmadan Yer Otomatik Tamamlama'yı programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Place Autocomplete - Request Per isteği göndermek 0,01132 ABD doları maliyete sahiptir. Bu nedenle, dört istek ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu maliyet, oturum başına 0,017 ABD doları olan Otomatik Tamamlama oturumu başına fiyattan daha düşüktür.1

Kullanıcılarınızın aradıkları tahmini daha da az karakterle almasına yardımcı olmak için performansla ilgili en iyi uygulamaları kullanmayı düşünebilirsiniz.

Hayır

Oturum tabanlı yer otomatik tamamlamayı Yer Ayrıntıları ile kullanın.
Kullanıcının bir Otomatik Yer Tamamlama tahminini seçmeden önce göndermenizi beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama uygulamanızda hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanılmalıdır.Bu durumda, toplam maliyet oturum başına 0,017 ABD dolarıdır.1

Widget uygulama
Oturum yönetimi, JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Buna hem yer otomatik tamamlama istekleri hem de seçili tahmindeki yer ayrıntıları isteği dahildir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programlı uygulama
Yer Otomatik Tamamlama isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları'nı talep ederken aşağıdaki parametreleri ekleyin:

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

Yer otomatik tamamlama isteklerini ertelemeyi düşünün
Uygulamanızın daha az istek göndermesi için kullanıcı ilk üç veya dört karakteri yazana kadar yer otomatik tamamlama isteğini erteleme gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteği gönderirseniz kullanıcı yedi karakter yazıp bir tahmin seçerse ve bu tahmin için bir Geocoding API isteği gönderirseniz toplam maliyet 0,01632 ABD doları olur (4 * 0,00283 ABD doları istek başına otomatik tamamlama + 0,005 ABD doları coğrafi kodlama).1

İstekleri ertelemeniz ortalama programatik isteğinizin dörtten az olmasını sağlayabilirse Geocoding API ile performanslı Yer Adı Otomatik Tamamlama uygulamasıyla ilgili yönergeleri uygulayabilirsiniz. Geciken isteklerin, her yeni tuş vuruşuyla tahminler 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 uygulamaları kullanabilirsiniz.

  1. Burada listelenen maliyetler ABD doları cinsindendir. Fiyatlandırmayla ilgili tüm bilgiler için lütfen Google Haritalar Platformu Faturalandırması sayfasına bakın.

Performansla ilgili en iyi uygulamalar

Aşağıdaki kurallarda, yer otomatik tamamlama performansını optimize etme yöntemleri açıklanmaktadır:

  • Yer Otomatik Tamamlama uygulamanıza ülke kısıtlamaları, konum önyargısı ve (programlı 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 dil tercihi gerekmez.
  • Yer Otomatik Tamamlama özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
  • Kullanıcının, otomatik tamamlama tahminlerinden birini seçmediği durumlarda (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) daha alakalı sonuçlar elde etmek amacıyla orijinal kullanıcı girişini yeniden kullanabilirsiniz:
    • Kullanıcıdan yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API çağrısında orijinal kullanıcı girişini yeniden kullanın.
    • Kullanıcının belirli bir yerle ilgili ad veya adresle sorgu girmesini bekliyorsanız Yer Bul isteği kullanın. Sonuçların yalnızca belirli bir bölgede elde edilmesi bekleniyorsa konumlu önyargı kullanın.
    Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
    • Bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adresleri giren kullanıcılar Örneğin, Çek adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
    • New York City'de "23-30 29th St, Queens" veya Hawai'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleriyle adres giren kullanıcılar.

Sorun giderme

Çeşitli hatalar oluşabilir ancak uygulamanızın karşılaşabileceği hataların çoğu genellikle yapılandırma hatalarından (örneğin, yanlış API anahtarı kullanıldı veya API anahtarı yanlış yapılandırıldı) 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 denetimlerinin kullanımında oluşan hatalar, onActivityResult() geri çağırma işlevinde döndürülür. Sonuçla ilgili durum mesajını almak için Autocomplete.getStatus() numaralı telefonu arayın.