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 tahminlerde bulunur. Kullanıcı yazarken otomatik tamamlama hizmeti; işletmeler, adresler, artı kodları ve önemli yerler gibi yerler için öneriler döndürür.

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

• Geliştirme zamanından tasarruf etmek ve tutarlı bir kullanıcı deneyimi sağlamak için otomatik tamamlama widget'ı ekleyin.
• Özelleştirilmiş bir kullanıcı deneyimi oluşturmak için yer tahminlerini programatik olarak alın.

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ğiniz tahmini yerlerin bir listesini sunar. Kullanıcı seçim yaptığında, uygulamanız seçili yerle ilgili ayrıntıları almak için kullanabileceği bir Place örneği döndürülür.

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

• 1. Seçenek: AutocompleteSupportFragment yerleştirme
• 2. Seçenek: Otomatik tamamlama etkinliğini başlatmak için bir amaç kullanın.

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 işleyici 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.
• Otomatik tamamlama parçasını kullanıyorsanız ve onActivityResult öğesini geçersiz kılmanız gerekiyorsa super.onActivityResult öğesini ç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 yer döndürme işlemini gerçekleştirir. Aşağıdaki kod, parçaya başvuru oluşturmayı ve AutocompleteSupportFragment öğenize bir işleyici eklemeyi gösterir:

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 bir amaç kullanma

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

Not: Bir parça yerleştiriyorsanız bu adımlar gerekli değildir.

Dikkat: AutcompleteActivity öğesini doğrudan BAŞLATMAYIN. Bunun yerine, Autocomplete (uyumluluk kitaplığında PlaceAutocomplete) öğesini başlatma niyeti kullanın.

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

1. İstenen 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şturun

Aşağıdaki örnekte, otomatik tamamlama widget'ını bir amaç olarak başlatma niyeti 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ı 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:

Şekil 1: OVERLAY modunda otomatik tamamlama widget'ı

Ş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 aşağıdaki örnekte gösterildiği gibi sonucu işleyen bir registerForActivityResult() başlatıcı tanımlayın. Kullanıcı bir tahmin seçtiyse bu tahmin, sonuç nesnesinde yer alan amaçta iletilir. Amaç Autocomplete.IntentBuilder tarafından derlendiği için Autocomplete.getPlaceFromIntent() yöntemi, Yer nesnesini bu öğeden 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'ı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 yer tahminlerini programatik olarak alması gerekir. Uygulamanız, aşağıdaki parametrelere sahip bir FindAutocompletePredictionsRequest nesnesi ileterek PlacesClient.findAutocompletePredictions() yöntemini çağırarak otomatik tamamlama API'sinden tahmini yer adlarının ve/veya adreslerinin bir listesini alabilir:

• Zorunlu: Kullanıcının yazdığı metni içeren bir query dizesi.
• Önerilen: AutocompleteSessionToken, faturalandırma amacıyla bir kullanıcı 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 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ını 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 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 durumlarda sonuçları netleştirmek 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 belirtilmiş bir adresi aradığını biliyorsanız bu türü kullanın.
  • TypeFilter.ESTABLISHMENT – Yalnızca işletme olan yerleri döndürür.

  • TypeFilter.REGIONS – Yalnızca aşağıdaki türlerden biriyle eşleşen yerleri döndürür:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

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

• İsteğe bağlı: İsteğin kaynak konumunu belirten bir LatLng. setOrigin() çağrısı yaptığınızda hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen kaynaktan uzaklığı 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() için yapılan tam bir çağrı gösterilmektedir.

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

API, Task içinde 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 bir kombinasyonudur. Örnek: "Eyfel Kulesi, Avenue Anatole France, Paris, Fransa". Buna ek olarak, 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 bu değeri 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 "İstiklal Caddesi No:123".
• 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 yararlıdır. Örnekler: "Ameka Anatole France, Paris, Fransa" ve "Sidney, Yeni Güney Galler".
• getPlaceId(), tahmin edilen yerin yer kimliğini döndürür. Yer kimliği, bir yeri benzersiz şekilde tanımlayan ve Place nesnesini daha sonra tekrar almak için kullanabileceğiniz metin biçimli bir tanımlayıcıdır. Android için Yerler SDK'sındaki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları'na bakın. Yer kimlikleri hakkında genel bilgi için Yer Kimliğine genel bakış sayfasına bakın.
• getPlaceTypes(), bu yerle ilişkili yer türlerinin listesini döndürür.
• getDistanceMeters(), bu yer ile istekte belirtilen kaynak arasındaki mesafeyi metre cinsinden döndürür.

İstek sınıflarından (örneğin, FetchPlaceRequest) herhangi birine yapılan bir isteği iptal etmeyi denemek için CancellationToken'ı kullanabilirsiniz. İptal işlemi, elimizden gelenin en iyisi yapılarak gerçekleştirilir. İptal isteği gönderildiğinde yanıt döndürülmez. İptal jetonu vermek, belirli bir isteğin iptal edileceğini garanti ETMEZ ve hiçbir yanıt döndürülmese bile istek için sizden ücret alınabilir.

Oturum jetonları

Oturum jetonları, faturalandırma amacıyla bir kullanıcı 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 kullanıcı bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu bulunabilir ve ardından tek bir yer seçimi yapılabilir. Bir oturum sonlandırıldıktan sonra 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 intent kullanarak otomatik tamamlama başlattığınızda API bunu otomatik olarak yapar).

Android için Yerler SDK'sı her oturumu tanımlamak için bir AutocompleteSessionToken kullanır. Uygulamanız her yeni oturumun başlangıcında yeni bir oturum jetonu iletmeli, ardından kullanıcı tarafından seçilen yerin Yer Ayrıntılarını almak için fetchPlace()'e yapılan sonraki çağrıda bir Yer Kimliği ile birlikte aynı jetonu iletmelidir.

Oturum jetonları hakkında daha fazla bilgi

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 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ölge dahilindeki 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() komutunu çağırın (örneğin, TypeFilter.ADDRESS belirtildiğinde yalnızca tam adresli sonuçlar döndürülür).
• Yalnızca en fazla beş ülke içindeki sonuçları döndürmek için setCountries() numaralı telefonu arayın. Ülkeler iki karakterlik, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.

Belirli bir bölge için yanlı sonuçlar

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre etkilemek için RectangularBounds ileterek setLocationBias() komutunu çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerinin Avustralya, Sidney'in bir bölgesine göre şekillendirilmesi için parça örneğinde setLocationBias() çağrısı gösterilmektedir.

Kotlin

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

      

Java

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

      

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

Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle kısıtlamak için bir RectangularBounds ileterek setLocationRestriction() komutunu çağırın. Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine göre etkilemek için bir parça ö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 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 koleksiyon türüne göre filtreleyin

Otomatik tamamlama isteğindeki sonuçları, yalnızca belirli bir yer türünü döndürecek şekilde kısıtlayabilirsiniz. Yer Türleri'ndeki 1, 2 ve 3. Tablolar'da 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.

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

• setTypesFilter() yöntemini çağırın ve Yer Türleri'nde gösterilen 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() yöntemini ç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 sabitlerle tanımlanır.

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

Aşağıdaki kod örneği, 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(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ı gösterilmektedir.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

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

      

Aşağıdaki kod örneğinde, bir tür koleksiyonu belirterek yalnızca kesin adrese sahip 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 filtreleyin

Otomatik tamamlama sonuçlarını en fazla beş ülkeye göre filtrelemek için setCountries() numarasını arayarak ülke kodunu ayarlayın. Ardından filtreyi bir parçaya veya amaca iletin. Ülkeler iki karakterlik, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.

Aşağıdaki kod örneğinde, yalnızca belirtilen ülkeler içindeki sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment için 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ğil. Ancak aşağıdaki kullanım sınırları geçerli olmaya devam eder:

• 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 taraflı ve sunucu tarafı isteklerin toplamı olarak hesaplanır.

İlişkilendirmeleri uygulamanızda gösterme

• Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüzde "Google tarafından desteklenmektedir" ilişkilendirmesi ya da Google markalı bir haritada yer alması gerekir.
• Uygulamanızda otomatik tamamlama widget'ı kullanılıyorsa başka bir 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ıp görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.

Daha fazla bilgi için ilişkilendirmeler hakkındaki belgeleri inceleyin.

Yer Otomatik 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 kurallar şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Otomatik tamamlama widget'ı, Android için Yerler SDK'sı Otomatik tamamlama widget'ı veya iOS için Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü'nü kullanmaktır
• Otomatik Yer Tamamlama veri alanları hakkında en baştan bilgi edinin.
• Konuma ağırlık verme ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
• API'nin hata döndürdüğü durumlarda uygulamanızın sorunsuz şekilde geri çekildiğinden emin olmak için hata işlemeyi kullanın.
• Uygulamanızın seçim yapılmadığında bunu işlendiğinden 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 hizmetini kullanma maliyetini optimize etmek için, Yer Ayrıntıları ve Otomatik Yer Tamamlama widget'larındaki alan maskelerini kullanarak yalnızca ihtiyacınız olan yer verisi alanlarını döndürün.

Gelişmiş maliyet optimizasyonu

İstek Başına Fiyatlandırma'ya erişmek ve seçilen yer hakkında Yer Ayrıntıları yerine Coğrafi Kodlama API'si sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik olarak uygulanmasını göz önünde bulundurun. Aşağıdaki koşulların her ikisi de karşılanırsa İstek Başına Fiyatlandırma, Geocoding API ile eşleştirilen Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyaç duyarsanız Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir ücret karşılığında sunar.
• Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmin 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 uyan Otomatik Yer Tamamlama uygulamasını seçme konusunda yardım almak için aşağıdaki soruya vereceğiniz yanıta karşılık gelen sekmeyi seçin.

Uygulamanız, seçilen tahminin adresi ve enlem/boylam dışında herhangi 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şletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gerektirdiğinden, Yer Otomatik Tamamlama özelliği programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunan bir oturum jetonu (programatik, Android ya da iOS widget'larında yerleşik) kullanmalıdır.Bunun için toplam maliyet 0, 017 ABD doları (oturum başına ve geçerli Yer Verileri SKU'ları yer verileri SKU'ları olmalıdır{/15).

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

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

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

Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak Coğrafi Kodlama API'sı, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Otomatik Tamamlama verimliliği, hangi kullanıcıların giriş yaptığına, 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 Yer Otomatik Tamamlama tahmini seçmeden önce ortalama kaç karakter yazdığını analiz edin.

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

Evet

Otomatik Yer Tamamlama özelliğini oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Coğrafi Kodlama API'sini çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını istek başına 0,005 ABD doları karşılığında sunar. Dört adet Otomatik Otomatik Tamamlama - İstek Başına istek göndermenin maliyeti 0,01132 ABD dolarıdır. Bu nedenle, seçilen yer tahminiyle ilgili dört isteğin toplam maliyeti ile birlikte Coğrafi Kodlama API'si çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu da oturum başına 0,017 ABD doları olan Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.¹

Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performans en iyi uygulamalarından yararlanmayı düşünebilirsiniz.

Hayır

Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Bir kullanıcı Otomatik Yer Tamamlama tahminini seçmeden önce gerçekleştirmeyi beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmayı aştığından, Yer Otomatik Tamamlama özelliği hem Otomatik Yer Tamamlama istekleri hem de bununla ilişkili Yer Ayrıntısı isteği için toplam oturum başına 0,017 ABD doları olmak üzere bir oturum jetonu kullanmalıdır.¹

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

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

1. Otomatik Yer 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

Otomatik Yer Tamamlama isteklerini ertelemeyi düşünün
Otomatik Yer Tamamlama isteğini, kullanıcı ilk üç veya dört karakteri yazana kadar ertelemek gibi stratejiler kullanarak uygulamanızın daha az istek göndermesini sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Tamamlama isteklerinde bulunmak, kullanıcı yedi karakteri yazdıktan sonra bir Coğrafi Kodlama API'si isteği gönderdiğiniz bir tahmin seçerse toplam maliyetin 0,01632 ABD doları (4 * 0,00283 ABD doları Otomatik Tamamlama + 0,005 ABD doları Coğrafi Kodlama) olacağı anlamına gelir.¹

İstekleri ertelemek ortalama programatik isteğinizin dörtün altına düşmesine neden oluyorsa Geocoding API ile otomatik yer tamamlama performansı uygulama yönergelerinden yararlanabilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahmin görmeyi bekleyen kullanıcılar tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha kısa sürede elde etmelerine yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

---

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

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansının optimize edilmesi için izlenecek yöntemler açıklanmaktadır:

• Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, konuma 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 cihazdan seçtiği için widget'larda dil tercihi yapmanız gerekmez.
• Otomatik Yer Tamamlama'ya bir harita eşlik ediyorsa, konumu harita görünümüne göre değiştirebilirsiniz.
• Kullanıcının Otomatik Tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden 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 belirli bir yer için ada veya adrese göre sorgu girmesini bekliyorsanız, Yer Bulma isteğini kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
  Geocoding API'nin en iyi seçenek olduğu diğer senaryolar şunlardır:
  • Şirket içi adresler için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerdeki (ör. Çekya, Estonya ve Litvanya) bina alt adreslerini giren kullanıcılar. Örneğin, Çekçedeki "Stroupežnického 3191/17, Praha" adresi, Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
  • New York City'de "23-30 29th St, Queens" veya Hawaii'deki Kauai Adası'nda "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleriyle adresler giren kullanıcılar.

Sorun giderme

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

Otomatik tamamlama denetimleri 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.