Otomatik Tamamla (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

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

Örneğin, giriş olarak kısmi bir kullanıcı girişi içeren bir dize ("Sicilian piz") kullanarak Otomatik Tamamlama'yı çağırırsınız. Arama alanı San Francisco, CA ile sınırlıdır. Ardından yanıtta, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesi (ör. "Sicilian Pizza Kitchen" adlı restoran) yer alır.

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 sınıfından bir nesne 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şlevinin tam çağrısı 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öğesinin listesini içerir. Sorguya ve filtre ölçütlerine karşılık gelen bilinen bir yer yoksa liste boş olabilir.

Tahmin edilen her yer için yer ayrıntılarını almak üzere aşağıdaki yöntemleri çağırabilirsiniz:

  • getFullText(CharacterStyle) bir yer açıklamasının tam metnini döndürür. Bu, birincil ve ikincil metnin bir kombinasyonudur. Örnek: "Eyfel Kulesi, Anatole France Caddesi, Paris, Fransa". Ayrıca bu yöntem, CharacterStyle kullanarak açıklamanın aramayla eşleşen bölümlerini seçtiğ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 tanımlayan 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 faydalı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 nesneyi 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 düz çizgi mesafesini 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 türü değerinin listesi. Bir yerin yanıta dahil edilmesi için belirtilen birincil tür değerlerinden biriyle eşleşmesi gerekir.

    Bir yerin, 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 elde edilen sonuçları dahil eder. Bu liste, en fazla 15 ccTLD ("üst düzey alan") 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 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 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ında olması gereken bölgeyi belirtme olarak düşünebilirsiniz. En önemli fark, konuma göre ağırlıklandırmada belirtilen 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ı olarak kullanılı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 bir 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 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, iki çapraz karşıt 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 sınırını içerir. Enlem sınırları -90 ile 90 derece (dahil) arasında, boylam sınırları ise -180 ile 180 derece (dahil) 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ıdır ve temsil edilen kutu boş bırakılamaz. 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 bir 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ı, 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 değildir. Uygulamanızın her oturum için yeni bir jeton oluşturması gerekir. Tüm programatik otomatik tamamlama oturumları için oturum jetonlarını kullanmanızı öneririz (Bir parçayı yerleştirdiğinizde veya otomatik tamamlamayı bir amaç kullanarak 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 göndermeli, ardından kullanıcı tarafından seçilen yerin yer ayrıntılarını almak için fetchPlace() işlevine yapılan sonraki çağrıda bu jetonu bir yer kimliğiyle birlikte göndermelidir.

    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ıları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ığı özelliğini 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ı, konumun bir önyargı olarak kullanılması anlamına gelir. Bu da, 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. Sonraki ö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 istekten elde edilen 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 kısıtlamak için birincil tür 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çlar, "athletic_field" gibi istemeyebileceğiniz türde tesisler içerebilir.

Kaynak kullan

İsteğe enlem ve boylam koordinatları olarak belirtilen origin parametresini eklediğinizde API, başlangıçtan 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());
        })
    );

İlişkilendirmeler

Otomatik Tamamlama'yı (Yeni) harita olmadan da kullanabilirsiniz. Gösterdiğiniz harita Google haritası olmalıdır. Otomatik Tamamlama (Yeni) hizmetinden gelen tahminleri harita olmadan görüntülerken 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.