Yer Adı Otomatik Tamamlama (Eski)

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Yer Adı Otomatik Tamamlama (Eski), kullanıcı arama sorgularına yanıt olarak yer tahminleri döndürür. Kullanıcı yazarken otomatik tamamlama hizmeti; işletmeler, adresler, Plus Code'lar ve ilgi çekici 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 yapabileceği tahmini yerlerin listesini sunar. Kullanıcı bir seçim yaptığında Place örneği döndürülür. Uygulamanız daha sonra bu örneği kullanarak seçilen yerle ilgili ayrıntıları alabilir.

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

1. seçenek: AutocompleteSupportFragment 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 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"
  />
  • Varsayılan olarak, parçanın 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.
  • Autocomplete parçasını kullanıyorsanız ve onActivityResult değerini geçersiz kılmanız gerekiyorsa super.onActivityResult işlevini çağırmanız gerekir. Aksi takdirde parça düzgün çalışmaz.

Bir etkinliğe PlaceSelectionListener ekleme

PlaceSelectionListener, kullanıcının seçimine yanıt olarak bir yerin döndürülmesini sağlar. Aşağıdaki kodda, parçaya referans oluşturma ve AutocompleteSupportFragment öğenize dinleyici ekleme işlemi 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(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 bir arama alanı yerine bir simgeden 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 intent oluşturmak için Autocomplete.IntentBuilder 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ı registerForActivityResult tanımlayın.

Otomatik tamamlama amacı oluşturma

Aşağıdaki örnekte, otomatik tamamlama widget'ını intent olarak başlatmak için intent oluşturmak üzere 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .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ından birini seçebilirsiniz. Aşağıdaki ekran görüntülerinde her bir görüntüleme modu sırasıyla gösterilmektedir:

Otomatik tamamlama widget'ı, yer paylaşımı modunda görüntülendiğinde arama kullanıcı arayüzünün üzerinde görünür.
Şekil 1: OVERLAY modunda otomatik tamamlama widget'ı
Tam ekran modunda görüntülendiğinde otomatik tamamlama widget'ı ekranın tamamını kaplar.
Şekil 2: Tam ekran modunda otomatik tamamlama widget'ı

Intent sonucu için geri çağırma kaydetme

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 intent içinde iletilir. Intent, Autocomplete.IntentBuilder tarafından oluşturulduğu için Autocomplete.getPlaceFromIntent() yöntemi, Place nesnesini intent'ten çıkarabilir.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                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ı tarafından yazılan metni içeren bir query dizesi.
  • Önerilen: Faturalandırma amacıyla bir kullanıcı aramasının sorgu ve seçim aşamalarını ayrı bir oturumda gruplandıran AutocompleteSessionToken. Oturum, kullanıcının sorgu yazmaya başlamasıyla başlar ve bir yer seçmesiyle sona erer.
  • Önerilen: RectangularBounds nesnesi. Bu nesne, sonuçları belirtilen bölgeyle sınırlamak için enlem ve boylam sınırlarını belirtir.
  • İsteğe bağlı: Sonuçların kısıtlanması gereken ülkeyi veya ülkeleri gösteren bir ya da daha fazla iki harfli ülke kodu (ISO 3166-1 Alfa-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çlardaki anlam belirsizliğini gidermek için bu isteği kullanın.
    • TypeFilter.ADDRESS: Yalnızca tam adrese sahip otomatik tamamlama sonuçlarını döndürür. Kullanıcının tam olarak belirtilmiş 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() yöntemini çağırdığınızda hizmet, yanıttaki her bir otomatik tamamlama tahmini için belirtilen başlangıç noktasından metre cinsinden mesafeyi (distanceMeters) 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() için eksiksiz 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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

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 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 birleşimidir. Ö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. Vurgulama gerekmiyorsa 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 alt metnini döndürür. Bu, örneğin otomatik tamamlama tahminleri gösterilirken ikinci 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 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 istiyorsanız 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 kaynak arasındaki düz çizgi mesafesini metre cinsinden döndürür.

Oturum jetonları

Oturum jetonları, faturalandırma amacıyla kullanıcının otomatik tamamlama aramasının sorgu ve seçim aşamalarını 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. 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ını kullanmanızı öneririz (bir parça yerleştirdiğinizde veya bir amaç kullanarak otomatik tamamlama başlattığınızda API bunu otomatik olarak halleder).

Android için Yerler SDK'sı, her oturumu tanımlamak için AutocompleteSessionToken kullanır. Uygulamanız, her yeni oturumun başında yeni bir oturum jetonu iletmeli, ardından kullanıcının seçtiği yerin yer ayrıntılarını almak için fetchPlace()'a yapılan sonraki çağrıda 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 kısıtlayabilir 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ı sınırlamak için aşağıdakileri yapın:

  • Tanımlanan bölgedeki sonuçları tercih etmek için setLocationBias() işlevini çağırın (Tanımlanan bölgenin dışındaki bazı sonuçlar yine de döndürülebilir).
  • Yalnızca tanımlanan bölgedeki sonuçları göstermek için setLocationRestriction() işlevini çağırın (yalnızca tanımlanan bölgedeki sonuçlar döndürülür).
  • Yalnızca belirli bir yer türüne uyan sonuçları döndürmek için setTypesFilter() yöntemini ç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ş ülkedeki sonuçları döndürmek için setCountries() yöntemini çağırın. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir.

Sonuçları belirli bir bölgeye göre önyargılı hale getirme

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre yönlendirmek için setLocationBias() işlevini çağırarak RectangularBounds değerini iletin. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine yönlendirmek için bir parça örneğinde setLocationBias() işlevinin nasıl çağrıldığı gösterilmektedir.

Kotlin

        autocompleteFragment.setLocationBias(bounds)

Java

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

Sonuçları belirli bir bölgeyle kısıtlama

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle sınırlamak için setLocationRestriction() işlevini çağırıp RectangularBounds değerini iletin. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine yönlendirmek için bir parça örneğinde setLocationRestriction() işlevinin nasıl çağrılacağı gösterilmektedir.

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

Java

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

Note: Bu kısıtlama yalnızca tüm rotalara uygulanır. Dikdörtgen sınırların dışında bulunan yapay sonuçlar, konum kısıtlamasıyla çakışan bir rotaya göre döndürülebilir.

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

Otomatik tamamlama isteğinden gelen sonuçları yalnızca belirli bir yer türünü 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() işlevini çağırın.

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

  • setTypesFilter() yöntemini çağırın ve Yer Türleri sayfasındaki Tablo 1 ve Tablo 2'den en fazla beş tür değeri belirtin. Tür değerleri, PlaceTypes içindeki sabitlerle 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 içindeki sabitler tarafından tanımlanır.

    İstekte Tablo 3'ten yalnızca 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 oluşur.

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

Kotlin

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

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

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

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(List.of(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.ESTABLISHMENT))
        .build(this)

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

Sonuçları ülkeye göre filtreleme

Otomatik tamamlama sonuçlarını en fazla beş ülkeye göre filtrelemek için setCountries() yöntemini çağırarak ülke kodunu ayarlayı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 AutocompleteSupportFragment üzerinde setCountries() işlevinin nasıl çağrılacağı gösterilmektedir.

Kotlin

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

Java

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

Kullanım sınırları

Android için Yerler SDK'sı (Eski) dahil olmak üzere Places API (Eski) 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 katkıları gösterme

  • Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüzde "Google tarafından desteklenmektedir" atfı gösterilmeli veya Google markalı bir harita yer almalıdır.
  • Uygulamanızda otomatik tamamlama widget'ı kullanılıyorsa ek bir işlem yapmanız gerekmez (gerekli ilişkilendirme varsayılan olarak gösterilir).
  • Kimliğe göre yer alma işleminden sonra ek yer bilgileri alıp görüntülerseniz üçüncü taraf ilişkilendirmelerini de görüntülemeniz gerekir.

Daha fazla bilgi için ilişkilendirmeler ile ilgili dokümanlara bakın.

Yer Adı Otomatik Tamamlama (Eski) optimizasyonu

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

Genel kurallardan bazıları şunlardır:

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Yer Adı Otomatik Tamamlama (Eski) hizmetini kullanma maliyetini optimize etmek için Yer Ayrıntıları (Eski) ve Yer Adı Otomatik Tamamlama (Eski) widget'larında alan maskeleri kullanarak yalnızca ihtiyacınız olan Yer Adı Otomatik Tamamlama (Eski) veri alanlarını döndürün.

Gelişmiş maliyet optimizasyonu

Yer Adı Otomatik Tamamlama (Eski) hizmetine programatik olarak erişmek için SKU: Autocomplete - Per Request pricing hizmetini kullanın ve Yer Ayrıntıları (Eski) yerine seçilen yerle ilgili Geocoding API sonuçları isteyin. Geocoding API ile eşlenen istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılandığında oturum başına (oturum tabanlı) fiyatlandırmadan daha uygun maliyetlidir:

  • Yalnızca kullanıcının seçtiği yerin enlem ve boylamına veya adresine ihtiyacınız varsa Geocoding API, bu bilgileri Place Details (Legacy) çağrısından daha düşük bir ücret karşılığında sağlar.
  • Kullanıcılar ortalama dört veya daha az Yer Adı Otomatik Tamamlama (Eski) tahmin isteği içinde bir otomatik tamamlama tahmini seçerse istek başına fiyatlandırma, oturum başına fiyatlandırmadan daha uygun maliyetli olabilir.
İhtiyaçlarınıza uygun Yer Adı Otomatik Tamamlama (Eski) uygulamasını seçme konusunda yardım almak için aşağıdaki soruya verdiğiniz cevaba karşılık gelen sekmeyi seçin.

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

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntıları (Eski) ile oturuma dayalı Yer Adı Otomatik Tamamlama (Eski) özelliğini kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları (Eski) bilgilerini gerektirdiğinden Yer Adı Otomatik Tamamlama (Eski) uygulamanızda oturum başına bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larına yerleşik olarak) ve istediğiniz yer verisi alanlarına bağlı olarak geçerli Places Data SKU'ları kullanılmalıdır.1

Widget uygulama
Oturum yönetimi, otomatik olarak JavaScript, Android, veya iOS widget'larına yerleştirilmiştir. Buna, seçilen tahmindeki hem Yer Adı Otomatik Tamamlama (Eski) istekleri hem de Yer Ayrıntıları (Eski) isteği dahildir. Yalnızca ihtiyacınız olan Yer Adı Otomatik Tamamlama (Eski) veri alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Yer Adı Otomatik Tamamlama (Eski) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Eski) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

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

Hayır, yalnızca adres ve konum bilgisi gerekiyor

Yer Adı Otomatik Tamamlama (Eski) kullanımınızın performansına bağlı olarak, Geocoding API, uygulamanız için Yer Ayrıntıları (Eski) API'sinden daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Yer Adı Otomatik Tamamlama (Eski) verimliliği; kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların hayata geçirilip geçirilmediğine bağlı olarak değişir.

Aşağıdaki soruyu yanıtlamak için bir kullanıcının uygulamanızda Yer Adı Otomatik Tamamlama (Eski) tahminini seçmeden önce ortalama kaç karakter yazdığını analiz edin.

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

Evet

Yer Adı Otomatik Tamamlama (Eski) özelliğini oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını sağlar. Dört Autocomplete - Per Request isteği ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısı yapmanın maliyeti, oturum başına Yer Adı Otomatik Tamamlama (Eski) maliyetinden daha düşüktür.1

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

Hayır

Yer Ayrıntıları (Eski) ile oturuma dayalı Yer Adı Otomatik Tamamlama (Eski) özelliğini kullanın.
Bir kullanıcı, Yer Adı Otomatik Tamamlama (Eski) tahmini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırmanın maliyetini aştığından Yer Adı Otomatik Tamamlama (Eski) uygulamanız hem Yer Adı Otomatik Tamamlama (Eski) istekleri hem de ilişkili Yer Ayrıntıları (Eski) isteği için oturum başına bir oturum jetonu kullanmalıdır. 1

Widget uygulama
Oturum yönetimi, JavaScript, Android, veya iOS widget'larına otomatik olarak yerleştirilmiştir. Buna hem Yer Adı Otomatik Tamamlama (eski) istekleri hem de seçilen tahminde Yer Ayrıntıları (eski) isteği dahildir. Yalnızca ihtiyacınız olan alanları istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Yer Adı Otomatik Tamamlama (Eski) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Eski) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

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

Yer Adı Otomatik Tamamlama (Eski) isteklerini geciktirmeyi düşünün
Uygulamanızın daha az istek göndermesi için Yer Adı Otomatik Tamamlama (Eski) isteğini kullanıcı ilk üç veya dört karakteri yazana kadar geciktirmek gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Adı Otomatik Tamamlama (Eski) isteğinde bulunmak, kullanıcının yedi karakter yazıp bir Geocoding API isteğinde bulunduğunuz bir tahmini seçmesi durumunda toplam maliyetin 4 Yer Adı Otomatik Tamamlama (Eski) İsteği + Coğrafi Kodlama olacağı anlamına gelir.1

İstekleri geciktirerek ortalama programatik istek sayınızı dörtten aşağıya düşürebilirseniz Coğrafi Kodlama API'si ile yüksek performanslı Yer Adı Otomatik Tamamlama (Eski) uygulamasıyla ilgili yönergeleri uygulayabilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahminleri 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 yararlanabilirsiniz.

  1. Maliyetler için Google Haritalar Platformu fiyat listelerine bakın.

Performansla ilgili en iyi uygulamalar

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

  • Yer Adı Otomatik Tamamlama (Eski) uygulamanıza ülkeye özgü kısıtlamalar, konum önceliği ve (programatik uygulamalar için) dil tercihleri ekleyin. Widget'lar, dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından aldığı için widget'larda dil tercihine gerek yoktur.
  • Yer Adı Otomatik Tamamlama (Eski) özelliğine harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
  • Kullanıcı, Yer Adı Otomatik Tamamlama (Eski) tahminlerinden birini seçmediğinde (genellikle bu tahminlerin 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ının 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 yer için ad veya adresle sorgu girmesini bekliyorsanız Yer Ayrıntıları (Eski) isteği kullanın. Sonuçların yalnızca belirli bir bölgede gösterilmesi bekleniyorsa konum ağırlıklandırmayı kullanın.
    Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
    • Kullanıcılar, bir bina içindeki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini girerken. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Yer Adı Otomatik Tamamlama (Eski) hizmetinde kısmi bir tahmin döndürür.
    • New York City'de "23-30 29th St, Queens" veya Hawaii'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti önekleri içeren adresleri giren kullanıcılar.

Konum tercihi

Bir location parametresi ve bir radius parametresi ileterek sonuçları belirli bir alana yönlendirin. Bu, Yer Adı Otomatik Tamamlama'ya (Eski) tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini söyler. Tanımlanan alanın dışındaki sonuçlar gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülkedeki yerleri gösterecek şekilde filtrelemek için includedRegionCodes parametresini kullanabilirsiniz.

Konum kısıtlama

locationRestriction parametresini ileterek sonuçları belirli bir alanla kısıtlayın.

Ayrıca, strictbounds parametresini ekleyerek sonuçları location ve radius parametresiyle tanımlanan bölgeyle kısıtlayabilirsiniz. Bu, Yer Adı Otomatik Tamamlama (Eski) özelliğine yalnızca bu bölgedeki sonuçları döndürmesi talimatını verir.

Sorun giderme

Çok çeşitli hatalar meydana gelebilse de uygulamanızın karşılaşabileceği hataların çoğu genellikle yapılandırma hatalarından (ör. 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 kontrollerinin kullanımında oluşan hatalar, onActivityResult() geri çağırmasında döndürülür. Sonuçla ilgili durum mesajını almak için Autocomplete.getStatus() işlevini çağırın.