Otomatik Tamamla (Yeni)

Otomatik Tamamlama (Yeni), arama alanını kontrol eden bir metin arama dizesi ve coğrafi sınırlar içeren bir isteğe yanıt olarak yer tahminleri döndürür. Otomatik tamamlama, girişin tam kelimeleri ve alt dizeleriyle eşleşebilir, yer adlarını, adresleri ve artı kodlarını çözebilir. Uygulamanız, kullanıcı yazarken anında yer ve sorgu tahminleri sağlamak için sorgu gönderebilir.

Örneğin, giriş olarak kısmi kullanıcı girişi içeren bir dize ("Sicilian piz") kullanarak otomatik tamamlama işlevini çağırıyorsunuz ve arama alanı San Francisco, CA ile sınırlı. Yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesini (ör. "Sicilian Pizza Kitchen" adlı restoran) içerir. Döndürülen yer tahminleri, kullanıcının istediği yeri seçmesine yardımcı olmak için tasarlanmıştır. Döndürülen yer tahminlerinden herhangi biri hakkında daha fazla bilgi edinmek için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.

Otomatik Tamamlama (Yeni) işlevini uygulamanıza iki ana şekilde entegre edebilirsiniz:

• Yer Otomatik Tamamlama widget'ını ekleyin: Kullanıcı yazarken tahminleri gösteren PlaceAutocomplete sınıfı aracılığıyla kullanıma hazır bir arama otomatik tamamlama deneyimi sunar.
• Yer tahminlerini programatik olarak alma: Tahminleri almak ve özel bir kullanıcı arayüzünde göstermek için doğrudan API'yi çağırın.

Yer Adı Otomatik Tamamlama widget'ını ekleme

Tutarlı bir yer otomatik tamamlama deneyimini daha kolay sağlamak için uygulamanıza Yer Otomatik Tamamlama widget'ını ekleyebilirsiniz. Widget, kullanıcı girişini işleyen ve yer tahminlerini kullanıcıya gösterirken uygulamaya AutocompletePrediction nesnelerini döndüren özel bir tam ekran arayüzü sağlar. Ardından, yer tahminlerinden herhangi biri hakkında ek bilgi almak için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.

Yer tahminlerini programatik olarak alma işleminde olduğu gibi, Yer Otomatik Tamamlama widget'ı, faturalandırma amacıyla otomatik tamamlama isteklerini oturumlar halinde gruplandırmak için oturum jetonlarını kullanmanıza olanak tanır. setAutocompleteSessionToken() işlevini çağırarak widget için amaç oluştururken oturum jetonu iletebilirsiniz. Oturum jetonu sağlamazsanız widget sizin için bir jeton oluşturur. Bu jetona getSessionTokenFromIntent() işlevini çağırarak erişebilirsiniz. Oturum jetonlarını kullanma hakkında daha fazla bilgi için Oturum jetonları hakkında başlıklı makaleye bakın.

Uygulamanıza yer otomatik tamamlama widget'ı eklemek için:

1. (İsteğe bağlı) Bir oturum jetonu tanımlayın. Oturum jetonu sağlamazsanız widget sizin için bir jeton oluşturur.

2. İstediğiniz parametrelerle ve oturum jetonunuzla bir autocompleteIntent tanımlayın.

3. StartActivityForResult için ActivityResultLauncher tanımlayın. Bu başlatıcı, otomatik tamamlama etkinliğinden döndürülen sonucu işler.

4. Sonucu ActivityResultLauncher geri çağırmasında işleyin. Bu işlemde AutocompletePrediction ve AutocompleteSessionToken (kendi AutocompletePrediction ve AutocompleteSessionToken'nizi sağlamadıysanız) ayıklama, hataları işleme ve isteğe bağlı olarak bir yerle ilgili ek ayrıntılar almak için fetchPlace() isteği gönderme yer alır.

5. placeAutocompleteActivityResultLauncher kullanarak intent'i başlatın.

Aşağıdaki örneklerde, hem Kotlin hem de Java kullanarak Yer Otomatik Tamamlama widget'ının nasıl ekleneceği gösterilmektedir:

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Temayı özelleştirme

Bir otomatik tamamlama deneyimi oluştururken, varsayılan stil özelliklerinden herhangi birini geçersiz kılan bir tema belirtebilirsiniz. Yer otomatik tamamlama bileşeninizin renklerini, tipografisini, boşluklarını, kenarlıklarını ve köşelerini özelleştirebilirsiniz. Varsayılan değer: PlacesMaterialTheme. Geçersiz kılınmayan tüm tema özellikleri varsayılan stilleri kullanır.

…/res/values/themes.xml içinde tema geçersiz kılmaları tanımlayabilirsiniz. Örneğin:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Daha sonra setAutocompleteUiCustomization çağrısı yaparak geçersiz kılma stillerine başvurabilirsiniz:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Yer tahminlerini programatik olarak alma

Uygulamanız, PlacesClient.findAutocompletePredictions() çağrısı yaparak ve FindAutocompletePredictionsRequest nesnesi ileterek otomatik tamamlama API'sinden tahmin edilen yer adlarının ve/veya adreslerin listesini alabilir. Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() için eksiksiz bir çağrı gösterilmektedir.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Otomatik tamamlama (yeni) yanıtları

API, FindAutocompletePredictionsResponse değerini Task içinde döndürür. FindAutocompletePredictionsResponse beş adede kadar AutocompletePrediction nesne listesi içerir. Bu nesneler, tahmin edilen yerleri temsil eder. 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. Hiçbir vurgulama yapmanız gerekmiyorsa bunu 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 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 biçimli bir tanımlayıcıdır. Bu tanımlayıcıyı kullanarak Place nesnesini daha sonra tekrar alabilirsiniz. Otomatik Tamamlama'daki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları (Yeni) bölümüne bakın. Yer kimlikleri hakkında genel bilgi için Yer kimliğine genel bakış başlıklı makaleyi inceleyin.
• getTypes() Bu yerle ilişkili yer türlerinin listesini döndürür.
• getDistanceMeters() bu yer ile istekte belirtilen başlangıç noktası arasındaki düz çizgi mesafesini metre cinsinden döndürür.

Gerekli parametreler

• Sorgu

  Arama yapılacak metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve artı kodları belirtin. Otomatik Tamamlama (Yeni) hizmeti bu dizeye göre olası eşleşmeleri döndürür ve sonuçları algılanan alaka düzeylerine göre sıralar.

  Sorgu parametresini ayarlamak için setQuery() yöntemini çağırın.FindAutocompletePredictionsRequest

İsteğe bağlı parametreler

• Birincil türler

  Yanıtla döndürülen yerleri filtrelemek için kullanılan, türler Tablo A veya Tablo B'den en fazla beş tür türü değerinin listesi. Yanıtın dahil edilmesi için bir yer, belirtilen birincil tür değerlerinden biriyle eşleşmelidir.

  Bir yer, yalnızca Tablo A veya Tablo B'de yer alan türlerden biriyle ilişkilendirilebilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir.

  İstek şu durumlarda INVALID_REQUEST hatasıyla reddedilir:

  • Beşten fazla tür belirtilmiş.
  • Tanınmayan türler belirtilir.

  Birincil türler parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setTypesFilter() yöntemini çağırın.

• Ülkeler

  Yalnızca belirtilen ülkelerin listesindeki sonuçları ekleyin. Bu ülkeler, en fazla 15 ccTLD ("üst düzey alan") iki karakterli değerden oluşan bir liste olarak belirtilir. Atlanırsa yanıta kısıtlama uygulanmaz. Örneğin, bölgeleri Almanya ve Fransa ile sınırlamak için:

  Hem locationRestriction hem de includedRegionCodes öğesini belirtirseniz sonuçlar iki ayarın kesişim alanında yer alır.

  Ülkeler parametresini ayarlamak için setCountries() yöntemini çağırın.FindAutocompletePredictionsRequest

• Giriş ofseti

  Sorgudaki imleç konumunu gösteren sıfır tabanlı Unicode karakteri uzaklığı. İmleç konumu, hangi tahminlerin döndürüleceğini etkileyebilir. Boş bırakılırsa varsayılan olarak sorgunun uzunluğu kullanılır.

  Giriş ofseti parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setInputOffset() yöntemini çağırın.

• Konum önyargısı veya konum kısıtlaması

  Arama alanını tanımlamak için konum tercihi veya konum kısıtlaması belirtebilirsiniz ancak ikisini birden belirtemezsiniz. Konum kısıtlamasını, sonuçların içinde olması gereken bölgeyi belirtme, konum tercihi ise sonuçların yakınında olması gereken bölgeyi belirtme olarak düşünebilirsiniz. Aradaki temel fark, konum önyargısı kullanıldığında belirtilen bölgenin dışındaki sonuçların da döndürülmeye devam edebilmesidir.

  • Konum önyargısı

    Arama yapılacak bir alanı belirtir. Bu konum, kısıtlama değil önyargı olarak kullanılır. Bu nedenle, belirtilen alanın dışındaki sonuçlar da döndürülebilir.

    Konum önyargısı parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setLocationBias() yöntemini çağırın.

  • Konum kısıtlaması

    Arama yapılacak bir alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez.

    Konum kısıtlama parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setLocationRestriction() yöntemini çağırın.

  Konum önyargısı veya konum kısıtlaması bölgesini dikdörtgen bir görüntü alanı ya da daire olarak belirtin.

  • Bir daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap 0,0 ile 50000,0 arasında (bu değerler dahil) olmalıdır. Varsayılan değer 0,0'dır. Konum kısıtlaması için yarıçapı 0,0'dan büyük bir değere ayarlamanız gerekir. Aksi takdirde, istek sonuç döndürmez.

  • Dikdörtgen, iki çapraz zıt low ve high noktası olarak gösterilen bir enlem-boylam görüntü alanıdır. Görüntü alanı, sınırını da içeren kapalı bir bölge olarak kabul edilir. Enlem sınırları -90 ile 90 derece arasında (bu değerler dahil), boylam sınırları ise -180 ile 180 derece arasında (bu değerler dahil) olmalıdır:

    • low = high ise görüntü alanı tek bir noktadan oluşur.
    • low.longitude > high.longitude ise boylam aralığı ters çevrilir (görüntü alanı 180 derece boylam çizgisini geçer).
    • low.longitude = -180 derece ve high.longitude = 180 derece ise görüntü alanı tüm boylamları içerir.
    • low.longitude = 180 derece ve high.longitude = -180 derece ise boylam aralığı boş olur.

    Hem low hem de high doldurulmalıdır ve gösterilen kutu boş olamaz. Boş bir görünüm penceresi hataya neden olur.

• Köken

  Hedefe olan düz çizgi mesafesinin hesaplanacağı başlangıç noktası (getDistanceMeters() kullanılarak erişilir). Bu değer atlanırsa düz çizgi mesafesi döndürülmez. Enlem ve boylam koordinatları olarak belirtilmelidir:

  Kaynak parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setOrigin() yöntemini çağırın.

• Bölge kodu

  Adres biçimlendirmesi de dahil olmak üzere yanıtı biçimlendirmek için kullanılan bölge kodu, ccTLD ("üst düzey alan") olarak belirtilen iki karakterli bir değerdir. Çoğu ccTLD kodu, ISO 3166-1 kodlarıyla aynıdır. Ancak bazı önemli istisnalar vardır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için).

  Geçersiz bir bölge kodu belirtirseniz API, INVALID_ARGUMENT hatası döndürür. Parametre, geçerli yasaya göre sonuçları etkileyebilir.

  Bölge kodu parametresini ayarlamak için setRegionCode() yöntemini FindAutocompletePredictionsRequest nesnesini oluştururken çağırın.

• Oturum jetonu

  Oturum jetonları, kullanıcı tarafından oluşturulan ve hem widget üzerinden yapılan aramaları hem de programatik aramaları "oturum" olarak izleyen dizelerdir. Otomatik Tamamlama, oturum jetonlarını kullanarak kullanıcının 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ının sorgu yazmaya başlamasıyla başlar ve bir yer seçmesiyle sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir. Bir oturum sona erdiğinde jeton geçerliliğini kaybeder. 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ça yerleştirdiğinizde veya bir amaç kullanarak otomatik tamamlama başlattığınızda API bunu otomatik olarak halleder).

  Otomatik Tamamlama, 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 jetonu parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setSessionToken() yöntemini çağırın.

  Daha fazla bilgi için Oturum jetonları başlıklı makaleyi inceleyin.

Otomatik tamamlama (yeni) örnekleri

Konum kısıtlaması ve konum önyargısı kullanma

Otomatik Tamamlama (Yeni), arama alanını kontrol etmek için varsayılan olarak IP önyargısını kullanır. IP önyargısı ile API, sonuçlara önyargı uygulamak için cihazın IP adresini kullanır. Arama yapılacak alanı belirtmek için isteğe bağlı olarak konum kısıtlaması veya konum tercihi'ni kullanabilirsiniz ancak ikisini birden kullanamazsınız.

Konum kısıtlaması, aranacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez. Aşağıdaki örnekte, isteği San Francisco'nun merkezinde 5.000 metre yarıçaplı dairesel bir konum kısıtlamasıyla sınırlamak için konum kısıtlaması kullanılmaktadır:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Konum önyargısında, konum bir önyargı olarak işlev görür. Bu nedenle, belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) döndürülebilir. Aşağıdaki örnekte, önceki istek konum önyargısı kullanacak şekilde değiştiriliyor:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Birincil türleri kullanma

Bir istekten gelen sonuçların Tablo A ve Tablo B'de listelenen belirli bir türde olmasını kısıtlamak için primary types parametresini kullanın. En fazla beş değerden oluşan bir dizi belirtebilirsiniz. Atlanırsa tüm türler döndürülür.

Aşağıdaki örnekte "Futbol" sorgu dizesi belirtiliyor ve sonuçları "sporting_goods_store" türündeki kuruluşlarla sınırlandırmak için primary_types parametresi kullanılıyor:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Birincil türler parametresini atlarsanız sonuçlar, "athletic_field" gibi istemeyebileceğiniz türde işletmeleri içerebilir.

Kaynağı kullanma

İsteğe enlem ve boylam koordinatları olarak belirtilen origin parametresini eklediğinizde API, yanıta başlangıç noktasından hedefe kadar olan düz çizgi mesafesini ekler (getDistanceMeters() kullanılarak erişilir). Bu örnekte başlangıç noktası San Francisco'nun merkezine ayarlanmıştır:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Otomatik tamamlama (yeni) optimizasyonu

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

Genel kurallardan bazıları şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu şunları kullanmaktır: Maps JavaScript API Autocomplete (New) widget, Android için Yerler SDK'sı Autocomplete (New) widget, veya iOS için Yerler SDK'sı Autocomplete (New) widget.
• Başlangıçtan itibaren temel Otomatik Tamamlama (Yeni) veri alanlarını anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
• API hata döndürürse uygulamanızın sorunsuz bir şekilde çalışmaya devam etmesini sağlamak için hata işlemeyi kullanın.
• Uygulamanızın seçim yapılmadığı durumları yönettiğinden ve kullanıcılara devam etme olanağı sunduğundan emin olun.

Maliyet optimizasyonu ile ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

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

Gelişmiş maliyet optimizasyonu

SKU: Otomatik Tamamlama İsteği fiyatlandırması'na erişmek için Otomatik Tamamlama (Yeni) özelliğini programatik olarak uygulayabilir ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Coğrafi Kodlama API sonuçları isteyebilirsiniz. Aşağıdaki koşulların her ikisi de karşılanıyorsa Geocoding API ile birlikte kullanılan istek başına fiyatlandırma, oturum başına (oturum tabanlı) fiyatlandırmaya kıyasla daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresi gerekiyorsa Geocoding API, bu bilgileri Place Details (New) çağrısından daha az bir ücret karşılığında sağlar.
• Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama (Yeni) tahmin isteği içinde bir otomatik tamamlama tahmini seçerse istek başına fiyatlandırma, oturum başına fiyatlandırmaya kıyasla daha uygun maliyetli olabilir.

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

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde, otomatik tamamlama (yeni) performansını optimize etmenin yolları açıklanmaktadır:

• Otomatik Tamamlama (Yeni) uygulamanıza ülke kısıtlamaları, konum önyargısı ve (programatik uygulamalar için) dil tercihi ekleyin. Dil tercihi, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini aldıkları için widget'larda gerekli değildir.
• Otomatik Tamamlama (Yeni) özelliğine harita eşlik ediyorsa harita görüntü alanına göre konumu önyargılı hale getirebilirsiniz.
• Kullanıcının, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için Otomatik Tamamlama (Yeni) tahminlerinden birini seçmediği durumlarda, daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
  • Kullanıcının yalnızca adres bilgisi gireceğini düşünüyorsanız Coğrafi Kodlama API'sine yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yerle ilgili sorguları ada veya adrese göre girmesini bekliyorsanız Yer Ayrıntıları (Yeni) isteğini kullanın. Sonuçların yalnızca belirli bir bölgede beklenmesi durumunda konum önyargısı 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, "Stroupežnického 3191/17, Praha" Çekçe adresi, otomatik tamamlama (yeni) özelliğinde kısmi bir tahminle sonuçlanır.
  • New York'ta "23-30 29th St, Queens" veya Hawaii'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresleri giren kullanıcılar.

Konum önyargısı

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana yönlendirin. Bu, otomatik tamamlama (yeni) özelliğine, tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini bildirir. Tanımlanan alanın dışındaki sonuçlar gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülke içindeki yerleri gösterecek şekilde filtrelemek için components parametresini kullanabilirsiniz.

Konum kısıtlama

locationRestriction parametresi ileterek sonuçları belirli bir alanla sınırlayın.

Ayrıca, location ve radius parametresiyle tanımlanan bölgeyle sonuçları kısıtlamak için locationRestriction parametresini ekleyebilirsiniz. Bu, Otomatik Tamamlama (Yeni) özelliğine yalnızca bu bölgedeki sonuçları döndürmesi talimatını verir.