Place Autocomplete

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:

• Geliştirme süresinden 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 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 yerleştirin.
• 2. seçenek: Otomatik tamamlama etkinliğini başlatmak için bir intent kullanın.

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:

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

      

    // 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:

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

      

    // 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 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:

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.

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

      

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.

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

      

    // 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 yapar).

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üyle ya da en fazla beş ülkeyle 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ölgesindeki bir bölgeye yönlendirmek için bir parça örneğinde setLocationBias() çağrısı gösterilmektedir.

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

      

    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.

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

      

    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 koleksiyonlarını 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() çağrısı yapı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.

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

      

    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.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    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.

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

    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.

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

      

    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'nın 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 bozulmasını 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 hizmetinin 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:

• Yalnızca kullanıcının seçtiği yerin 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.

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

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 kaydırabilirsiniz.
• 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.