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 tahminlerini döndürür. Otomatik tamamlama, girişin tam kelimeleri ve alt dizeleriyle eşleşerek yer adlarını, adresleri ve artı kodlarını çözümleyebilir. Uygulamanız, anında yer ve sorgu tahminleri sağlamak için kullanıcı yazarken sorgular gönderebilir.

Örneğin, kısmi kullanıcı girişini içeren "Sicilian piz" ifadesini içeren bir dize kullanarak Otomatik Tamamlama'yı çağırabilirsiniz. Arama alanı San Francisco, Kaliforniya ile sınırlıdır. Daha sonra yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin (ör. "Sicilian Pizza Kitchen" adlı restoran) bir listesini içerir.

Döndürülen yer tahminleri, kullanıcıya istenen yeri seçmesine yardımcı olmak amacıyla sunulacak şekilde tasarlanmıştır. Döndürülen yer tahminlerinden herhangi biri hakkında daha fazla bilgi almak için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.

Otomatik tamamlama (Yeni) istekleri

Uygulamanız, bir FindAutocompletePredictionsRequest nesnesi ileterek PlacesClient.findAutocompletePredictions() yöntemini çağırarak otomatik tamamlama API'sinden tahmini yer adlarının ve/veya adreslerinin bir listesini alabilir. Aşağıdaki örnekte, PlacesClient.findAutocompletePredictions() için 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, tahmin edilen yerleri temsil eden en fazla beş AutocompletePrediction nesnesinin yer aldığı bir liste 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, Avenue Anatole France, Paris, Fransa". Buna ek olarak, 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 bu değeri 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 "İstiklal Caddesi No:123".
  • 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 yararlıdır. Örnekler: "Ameka Anatole France, Paris, Fransa" ve "Sidney, Yeni Güney Galler".
  • getPlaceId(), tahmin edilen yerin yer kimliğini döndürür. Yer kimliği, bir yeri benzersiz şekilde tanımlayan ve Place nesnesini daha sonra tekrar almak için kullanabileceğiniz metin biçimli bir tanımlayıcıdır. 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ış sayfasına bakın.
  • getTypes(), bu yerle ilişkili yer türlerinin listesini döndürür.
  • getDistanceMeters(), bu yer ile istekte belirtilen kaynak arasındaki mesafeyi 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ını belirtin. Otomatik Tamamlama (Yeni) hizmeti, bu dizeye dayalı aday eşleşmeleri döndürür ve sonuçları algılanan alaka düzeyine 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ğeri içeren bir liste. Bir yerin yanıta dahil edilmesi için belirtilen birincil tür değerlerinden biriyle eşleşmesi gerekir.

    Bir yerin kendisiyle ilişkili Tablo A veya Tablo B türlerinden yalnızca tek 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 belirtilmiş.

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

  • Ülkeler

    Yalnızca belirtilen ülkeler listesinden, en fazla 15 ccTLD ("üst düzey alan") iki karakterlik değerden oluşan bir liste olarak belirtilen sonuçları dahil edin. 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 öğesini belirtirseniz sonuçlar iki ayarın kesişim alanında yer alır.

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

  • Giriş ofseti

    Sorgudaki imlecin konumunu gösteren sıfır tabanlı Unicode karakter farkı. İmleç konumu, hangi tahminlerin döndürüleceğini etkileyebilir. Boşsa varsayılan olarak sorgunun uzunluğuna göre ayarlanır.

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

  • Konum sapması veya konum kısıtlaması

    Arama alanını tanımlamak için konum tercihi veya konum kısıtlaması belirtebilirsiniz ancak ikisini birden yapamazsınız. Konum kısıtlamasını, sonuçların içinde olması gereken bölgeyi belirtmek, konum ön yargısını ise sonuçların yakınında olması gereken bölgeyi belirtmek olarak düşünebilirsiniz. Aradaki temel fark, konum yanlılığı olduğunda belirtilen bölgenin dışındaki sonuçların döndürülebilmesidir.

    • Konum ön yargısı

      Aranacak alanı belirtir. Bu konum bir kısıtlama değil, sapmadır. Bu nedenle, belirtilen alanın dışındaki sonuçlar yine de döndürülebilir.

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

    • Konum kısıtlaması

      Aranacak 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 sapmasını veya konum kısıtlama bölgesini dikdörtgen Viewport veya daire olarak belirtin.

    • Bir daire, merkez noktası ve metre cinsinden yarıçapla tanımlanır. Yarıçap, 0,0 ile 50.000,0 (her ikisi de dahil) 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, köşeye çapraz low ve high noktayla gösterilen bir enlem-boylam görüntü alanıdır. Görüntü alanı, kapalı bölge olarak kabul edilir. Yani kendi sınırlarını içerir. Enlem sınırları -90 ile 90 derece (dahil) arasında, boylam sınırları ise -180 ila 180 derece (her ikisi de dahil) arasında olmalıdır:

      • low = high olursa, görüntü alanı bu tek noktadan oluşur.
      • low.longitude > high.longitude ise boylam aralığı tersine çevrilir (görüntü alanı 180 derecelik 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 gösterilen kutu boş bırakılamaz. Boş 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 de dahil olmak üzere yanıtı biçimlendirmek için kullanılan, iki karakterli ccTLD ("üst düzey alan") olarak belirtilen bölge kodu. ccTLD kodlarının çoğu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu "gb" (teknik olarak "Büyük Britanya ve Kuzey İrlanda'daki Birleşik Krallık'a" ait tüzel kişi için) "gb" şeklindedir.

    Geçersiz bir bölge kodu belirtirseniz API, INVALID_ARGUMENT hatası döndürür. Parametre, geçerli yasalara 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şturulmuş dizelerdir. Otomatik tamamlama, kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırmak için oturum jetonları kullanır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve kullanıcı bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu bulunabilir ve ardından tek bir yer seçimi yapılabilir. Oturum sona erdiğinde jeton artık geçerli olmaz. Bu nedenle uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm programatik otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz (bir parçayı yerleştirdiğinizde veya bir intent kullanarak otomatik tamamlama başlattığınızda API bunu otomatik olarak yapar).

    Otomatik tamamlama, her bir oturumu tanımlamak için bir AutocompleteSessionToken simgesi kullanır. Uygulamanız her yeni oturumun başlangıcında yeni bir oturum jetonu iletmeli, ardından kullanıcı tarafından seçilen yerin Yer Ayrıntılarını almak için fetchPlace()'e yapılan sonraki çağrıda bir Yer Kimliği ile birlikte aynı jetonu 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ünü inceleyin.

Otomatik tamamlama (Yeni) örnekleri

Konum kısıtlaması ve konum ağırlıklandırmasını kullan

Otomatik Tamamlama (Yeni), arama alanını kontrol etmek için varsayılan olarak IP ağırlıklandırmayı kullanır. IP'ye ağırlık vermede API, sonuçlara yanlılık eklemek 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 ön yargısı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ıçapında bir dairesel 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 yanlılığı ile konum, bir yanlılık görevi görür. Bu da belirtilen konumun çevresindeki sonuçların, belirtilen alanın dışındaki sonuçlar da dahil olmak üzere döndürülebileceği anlamına gelir. Sonraki örnek, konum yanlılığını kullanmak için önceki isteği değiştirir:

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 kullan

Bir istekten gelen sonuçları Tablo A ve B Tablosu'nda 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" sorgu dizesi belirtilmektedir ve sonuçları "sporting_goods_store" türündeki kuruluşlarla kısıtlamak için birincil türler parametresi kullanılmaktadı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 çıkarırsanız sonuçlar, "athletic_field" gibi istemediğiniz bir türdeki kuruluşları içerebilir.

Kaynağı kullan

Enlem ve boylam koordinatları olarak belirtilen origin parametresini isteğe eklediğinizde API, yanıtta başlangıç noktası ile hedefe arasındaki düz çizgiyi içerir (getDistanceMeters() kullanılarak erişilir). Bu örnekte, başlangıç noktası San Francisco'nun merkezi olarak ayarlanmaktadı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 (Yeni) özelliğini harita olmadan da kullanabilirsiniz. Harita gösterecekseniz bu bir Google haritası olmalıdır. Otomatik Tamamlama (Yeni) hizmetinden alınan tahminleri harita olmadan görüntülediğinizde, arama alanında/sonuçlarında satır içinde görüntülenen Google logosunu eklemeniz gerekir. Daha fazla bilgi için Google logosunu ve ilişkilendirmeleri görüntüleme bölümüne bakın.