Otomatik Tamamla (Yeni)

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

Örneğin, Autocomplete'i kısmi kullanıcı girişi içeren bir dizeyi ("Sicilian piz") giriş olarak kullanarak çağırırsınız ve arama alanını San Francisco, CA ile sınırlarsınız. Yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesini içerir. Örneğin, "Sicilian Pizza Kitchen" adlı restoran. 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ı (New) isteğinde bulunabilirsiniz.

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

• Yer Adı 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 bunları ö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 Adı Otomatik Tamamlama deneyimini daha kolay sağlamak için uygulamanıza Yer Adı Otomatik Tamamlama widget'ını ekleyebilirsiniz. Widget, kullanıcı girişini işleyen ve yer tahminlerini kullanıcıya gösteren özel bir tam ekran arayüz sağlar. Ayrıca, uygulamaya AutocompletePrediction nesnelerini döndürür. Ardından, yer tahminleriyle ilgili ek bilgi almak için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.

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

Yer Adı Otomatik Tamamlama widget'ını uygulamanıza 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 parametreleri ve oturum jetonunuzu içeren 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ğırma işlevinde işleyin. Bu işlem, AutocompletePrediction ve AutocompleteSessionToken (kendi anahtarınızı sağlamadıysanız) ayıklamayı, hataları işlemeyi ve isteğe bağlı olarak bir yer hakkında ek ayrıntılar almak için fetchPlace() isteği göndermeyi içerir.

5. placeAutocompleteActivityResultLauncher kullanarak amacı başlatın.

Aşağıdaki örneklerde, Kotlin ve Java kullanarak Yer Adı 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

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

…/res/values/themes.xml içinde tema geçersiz kılma işlemleri 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() yöntemini çağırıp bir FindAutocompletePredictionsRequest nesnesi ileterek otomatik tamamlama API'sinden tahmini yer adlarının ve/veya adreslerinin 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, bir Task içinde FindAutocompletePredictionsResponse döndürür. FindAutocompletePredictionsResponse , tahmin edilen yerleri temsil eden en fazla beş AutocompletePrediction nesnesinin 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 aşağıdaki yöntemleri çağırarak yer ayrıntılarını alabilirsiniz:

• 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 bu değeri boş bırakı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 Street".
• getSecondaryText(CharacterStyle), bir yer açıklamasının alt 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, France" 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. Otomatik Tamamlama'daki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları (Yeni) başlıklı makaleyi inceleyin. Yer kimlikleri hakkında genel bilgi için Yer kimliği 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 kaynak arasındaki düz çizgi mesafesini metre cinsinden döndürür.

Gerekli parametreler

• Sorgu

  Aranacak metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve Plus Kodları belirtin. Autocomplete (New) hizmeti, bu dizeye göre eşleşme adayları 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ıt olarak döndürülen yerleri filtrelemek için kullanılan, türlerden en fazla beş tür türü değerinin listesi Tablo A veya Tablo B. Yanıtın dahil edilmesi için bir yer, belirtilen birincil tür değerlerinden biriyle eşleşmelidir.

  Bir yerin, Tablo A veya Tablo B'deki türlerden yalnızca bir birincil türü olabilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir.

  İstek, aşağıdaki durumlarda INVALID_REQUEST hatasıyla reddedilir:

  • Beşten fazla tür belirtilmiş.
  • Tanınmayan türler belirtildiğinde

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

• Ülkeler

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

  Hem locationRestriction hem de includedRegionCodes 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 karakter ofseti. İ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 setInputOffset() yöntemini çağırın.FindAutocompletePredictionsRequest

• 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 belirtmek, konum eğilimini ise sonuçların yakınında olması gereken bölgeyi belirtmek olarak düşünebilirsiniz. Buradaki temel fark, konum önyargısı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 tercihi 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 tercihi veya konum kısıtlama bölgesini dikdörtgen bir görüntü alanı ya da daire olarak belirtin.

  • Daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap, 0,0 ile 50.000,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 köşesi çapraz olarak birbirine bakan low ve high noktalarıyla gösterilen bir enlem-boylam görünüm alanıdır. Görüntü alanı, kapalı bir bölge olarak kabul edilir. Yani sınırını da içerir. 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 temsil edilen kutu boş olamaz. Boş bir görünüm penceresi hataya neden olur.

• Köken

  Hedefe 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") iki karakterli değeri olarak belirtilir. Bazı önemli istisnalar dışında çoğu ccTLD kodu, ISO 3166-1 kodlarıyla aynıdı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 FindAutocompletePredictionsRequest nesnesini oluştururken setRegionCode() yöntemini çağırın.

• Oturum jetonu

  Oturum jetonları, kullanıcı tarafından oluşturulan ve hem widget üzerinden yapılan hem de programatik olarak yapılan Otomatik Tamamlama (Yeni) çağrılarını "oturum" olarak izleyen dizelerdir. Otomatik tamamlama, faturalandırma amacıyla bir kullanıcının otomatik tamamlama aramasının sorgu ve seçim aşamalarını ayrı bir oturumda gruplandırmak için oturum jetonlarını kullanı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 erdikten 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 tamamlamayı başlattığınızda API bunu otomatik olarak yapar).

  Otomatik tamamlama, her oturumu tanımlamak için bir AutocompleteSessionToken kullanır. Uygulamanız her yeni oturumun başında yeni bir oturum jetonu iletmeli, ardından kullanıcı tarafından seçilen yerin Yer Ayrıntıları'nı almak için fetchPlace() yöntemine 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 tercihi kullanma

Otomatik tamamlama (yeni), arama alanını kontrol etmek için varsayılan olarak IP önyargısını kullanır. IP ağırlıklandırma ile API, sonuçları ağırlıklandırmak için cihazın IP adresini kullanır. Arama yapılacak bir alanı belirtmek için isteğe bağlı olarak konum kısıtlaması veya konum eğilimi kullanabilirsiniz ancak ikisini birden kullanamazsınız.

Konum kısıtlaması, arama yapılacak 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ılıyor:

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 etrafındaki 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

İsteğin sonuçlarını Tablo A ve Tablo B'de listelenen belirli bir türle sınırlamak 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ırlamak için birincil türler 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.

Kaynak kullan

İsteğe enlem ve boylam koordinatları olarak belirtilen origin parametresini eklediğinizde API, başlangıç noktasından hedefe olan düz çizgi mesafesini yanıta ekler (getDistanceMeters() kullanılarak erişilir). Bu örnekte başlangıç noktası San Francisco'nun merkezi olarak 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'ı.
• Temel Autocomplete (New) veri alanlarını en baştan anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
• 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ığında bu durumu ele aldığından ve kullanıcılara devam etme yolu sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Tamamlama (Yeni) hizmetini kullanma 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: Autocomplete Request fiyatlandırmasına erişmek için Autocomplete'in (Yeni) programatik uygulamasını kullanmayı ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçlarını istemeyi düşünün. Aşağıdaki koşulların her ikisi de karşılanıyorsa istek başına fiyatlandırma, Geocoding API ile birlikte kullanıldığında oturum başına (oturum tabanlı) fiyatlandırmaya kıyasla 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 Yer Ayrıntıları (Yeni) çağrısından daha düşük 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ırmadan daha uygun maliyetli olabilir.

Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında başka 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 ülkeye özgü kısıtlamalar, konum ağırlığı ve (programatik uygulamalar için) dil tercihleri ekleyin. Dil tercihi, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini alan widget'larda gerekli değildir.
• Autocomplete (New) özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcı, Otomatik Tamamlama (Yeni) tahminlerinden birini seçmediğinde (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ı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ı (Yeni) 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 binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini giriyor. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha" için Otomatik Tamamlama (Yeni) özelliğinde kısmi bir tahmin elde edilir.
  • Kullanıcılar, New York'ta "23-30 29th St, Queens" veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresler giriyor.

Konum önyargısı

Bir location parametresi ve bir radius parametresi ileterek sonuçları belirli bir alana yönlendirin. Bu, Otomatik Tamamlama'ya (Yeni) 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 sınırlayın.

Ayrıca, locationRestriction parametresini ekleyerek sonuçları location ve radius parametresiyle tanımlanan bölgeyle kısıtlayabilirsiniz. Bu, Otomatik Tamamlama (Yeni) özelliğine yalnızca o bölgedeki sonuçları döndürmesini bildirir.