Otomatik Tamamla (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

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, yer adlarını, adresleri ve plus kodlarını çözerek girişin tam kelimelerini ve alt dizelerini eşleştirebilir. Uygulamanız, anında yer ve sorgu tahminleri sunmak için kullanıcı yazarken sorgu gönderebilir.

Örneğin, giriş olarak kısmi bir kullanıcı girişi içeren bir dize ("Sicilian piz") kullanarak otomatik tamamlamayı çağırırsınız. Arama alanı, San Francisco, CA ile sınırlıdır. Yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesini içerir (ör. "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 kullanıcıya sunulmak üzere 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ği gönderebilirsiniz.

Otomatik Tamamlama (Yeni) istekleri

Uygulamanız, FindAutocompletePredictionsRequest nesnesi göndererek PlacesClient.findAutocompletePredictions() işlevini çağırarak otomatik tamamlama API'sinden tahmin edilen yer adlarının ve/veya adreslerin listesini alabilir. Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() işlevine yapılan tam 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, Task içinde bir FindAutocompletePredictionsResponse döndürür. FindAutocompletePredictionsResponse, öngörülen 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 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. 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ğ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 doğrusal mesafeyi metre cinsinden döndürür.

Gerekli parametreler

  • Sorgu

    Aramanın yapılacağı metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve artı kodlarını 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 FindAutocompletePredictionsRequest nesnesini oluştururken setQuery() yöntemini çağırın.

İsteğe bağlı parametreler

  • Birincil türler

    Yanıtta döndürülen yerleri filtrelemek için kullanılan Tablo A veya Tablo B türlerinden en fazla beş tür değerinin listesi. Bir yerin yanıta dahil edilebilmesi için belirtilen birincil tür değerlerinden biriyle eşleşmesi gerekir.

    Bir yerin, ilişkili Tablo A veya Tablo B türlerinden yalnızca bir birincil türü olabilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir.

    Aşağıdaki durumlarda istek INVALID_REQUEST hatasıyla reddedilir:

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

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

  • Ülkeler

    Yalnızca belirtilen ülkeler listesinden gelen sonuçları dahil edin. Bu liste, en fazla 15 ccTLD ("üst düzey alan") iki karakterli değerden oluşmalıdır. 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 bulunur.

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

  • Giriş ofseti

    Sorgudaki imleç konumunu gösteren sıfır tabanlı Unicode karakter ofseti. İmlecin konumu, döndürülen tahminleri etkileyebilir. Boş bırakılırsa varsayılan olarak sorgunun uzunluğuna ayarlanır.

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

  • Konum yanlılığı veya konum kısıtlaması

    Arama alanını tanımlamak için bir konum yanlılığı 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 önyargısını ise sonuçların yakın olması gereken bölgeyi belirtme olarak düşünebilirsiniz. Aradaki temel fark, konum önyargısıyla belirlenen bölgenin dışındaki sonuçların da döndürülebilmesidir.

    • Konum yanlılığı

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

      Yer yanlılığı 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ıtlaması parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setLocationRestriction() yöntemini çağırın.

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

    • Daireler, merkez noktası ve yarıçapı (metre cinsinden) 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 hiçbir sonuç döndürmez.

    • Dikdörtgen, çapraz olarak karşı karşıya duran iki low ve high noktası olarak temsil edilen bir enlem-boylam görüntü alanıdır. Görüntü alanı kapalı bir bölge olarak kabul edilir. Yani kendi sınırını içerir. Enlem sınırları -90 ile 90 derece arasında, boylam sınırları ise -180 ile 180 derece arasında olmalıdır:

      • low = high ise görüntü alanı tek bir noktadan oluşur.
      • low.longitude > high.longitude ise boylam aralığı tersine ç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ı ve temsil edilen kutu boş olmamalıdır. Boş bir görüntü alanı hatayla sonuçlanır.

  • 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 dahil olmak üzere yanıtı biçimlendirmek için kullanılan bölge kodu. ccTLD ("üst düzey alan") iki karakterli bir değer 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ı verir. 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ı, Otomatik Tamamlama (Yeni) çağrılarını "oturumlar" olarak izleyen, kullanıcı tarafından oluşturulan dizelerdir. Otomatik Tamamlama, faturalandırma amacıyla kullanıcı 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 bulunabilir. 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).

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

    Daha fazla bilgi için Oturum jetonları bölümüne bakın.

Otomatik tamamlama (yeni) örnekleri

Konum kısıtlaması ve konum yanlılığı kullanma

Otomatik Tamamlama (Yeni), arama alanını kontrol etmek için varsayılan olarak IP önyargısını kullanır. IP önyargısı, sonuçları önyargılı hale getirmek için API'nin cihazın IP adresini kullanmasıdır. Arama yapılacak bir alanı belirtmek için isteğe bağlı olarak konum kısıtlaması veya konum yanlılığı'nı 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 merkezli 5.000 metre yarıçaplı dairesel bir konum kısıtlamasıyla sınırlamak için konum kısıtlaması kullanılı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ı, konumun bir önyargı olarak kullanılması anlamına gelir. Bu, belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumun çevresindeki sonuçların döndürülebileceği anlamına gelir. Aşağıdaki örnekte, önceki istek konum önyargısı kullanacak şekilde değiştirilmiştir:

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 istekteki sonuçları Tablo A ve Tablo B'de listelenen belirli bir türde olacak şekilde kısıtlamak için birincil türler 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" şeklinde bir sorgu dizesi belirtilmiştir ve sonuçları "sporting_goods_store" türündeki tesislerle sınırlandırmak için primarytypes parametresi kullanılmıştır:

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çlarda "athletic_field" gibi istemeyebileceğiniz türde tesisler bulunabilir.

Kaynağı kullanma

İsteğe enlem ve boylam koordinatları olarak belirtilen origin parametresini eklediğinizde API, başlangıçtan hedefe kadar olan düz çizgi mesafesini yanıta ekler (getDistanceMeters() kullanılarak erişilir). Bu örnekte, başlangıç 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());
        })
    );

İlişkilendirmeler

Otomatik Tamamlama'yı (Yeni) harita olmadan da kullanabilirsiniz. Harita göstermek istiyorsanız bu Google haritası olmalıdır. Otomatik Tamamlama (Yeni) hizmetinden gelen tahminleri harita olmadan gösterdiğinizde arama alanı/sonuçlarla satır içi olarak gösterilen Google logosunu eklemeniz gerekir. Daha fazla bilgi için Google logosunu ve ilişkilendirmeleri görüntüleme başlıklı makaleyi inceleyin.