Otomatik Tamamlama (Yeni), arama alanını kontrol eden bir metin arama dizesi ve coğrafi sınırlar içeren bir istekle yanıt olarak yer tahminleri döndürür. Otomatik tamamlama, girişin tam kelimelerini ve alt dizelerini eşleştirerek yer adlarını, adresleri ve plus kodlarını çözebilir. 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ıtta, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesi yer alır. Ö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 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) işlevini uygulamanıza iki temel şekilde entegre edebilirsiniz:
- Yer Otomatik Tamamlama widget'ını ekleme: Kullanıcı yazarken tahminleri gösteren
PlaceAutocomplete
sınıfı aracılığıyla hazır bir arama otomatik tamamlama deneyimi sunar. - Yer tahminlerini programatik olarak alma: Tahminleri almak ve özel bir kullanıcı arayüzünde görüntülemek için API'yi doğrudan çağırın.
Yer Adı Otomatik Tamamlama widget'ını ekleme
Tutarlı bir yer otomatik tamamlama deneyimi sunmak için uygulamanıza Yer Otomatik Tamamlama widget'ını ekleyebilirsiniz. Widget, kullanıcı girişini işleyen ve uygulamaya AutocompletePrediction
nesneleri döndürürken kullanıcıya yer tahminlerini gösteren özel, tam ekran bir arayüz sağlar. Ardından, yer tahminlerinden herhangi biri hakkında ek bilgi almak için Yer Ayrıntıları (Yeni) isteği gönderebilirsiniz.
Yer tahminlerini programatik olarak alma işleminde olduğu gibi, Yer Otomatik Tamamlama widget'ı da faturalandırma amacıyla otomatik tamamlama isteklerini oturumlara gruplandırmak için oturum jetonlarını kullanmanıza olanak tanır. setAutocompleteSessionToken()
işlevini çağırarak widget'ın amacını oluştururken oturum jetonu iletebilirsiniz. Oturum jetonu sağlamazsanız widget sizin için bir jeton oluşturur. Bu jetona getSessionTokenFromIntent()
çağrısı yaparak erişebilirsiniz. Oturum jetonlarını kullanma hakkında daha fazla bilgi için Oturum jetonları hakkında başlıklı makaleyi inceleyin.
Yer Otomatik Tamamlama widget'ını uygulamanıza eklemek için:
(İsteğe bağlı) Oturum jetonu tanımlayın. Oturum jetonu sağlamazsanız widget sizin için bir jeton oluşturur.
İstediğiniz parametreleri ve oturum jetonunuzu içeren bir
autocompleteIntent
tanımlayın.StartActivityForResult
için birActivityResultLauncher
tanımlayın. Bu başlatıcı, otomatik tamamlama etkinliğinden döndürülen sonucu işler.Sonuçları
ActivityResultLauncher
'ın geri aramasında işleyin. Bu işlem,AutocompletePrediction
veAutocompleteSessionToken
'yi (kendinizin sağlamadıysanız) ayıklamak, hataları işlemek ve isteğe bağlı olarak bir yer hakkında ek ayrıntılar almak içinfetchPlace()
isteği göndermeyi içerir.placeAutocompleteActivityResultLauncher
'ü kullanarak intent'i başlatın
Aşağıdaki örneklerde, hem Kotlin hem de Java kullanılarak Yer Otomatik Tamamlama widget'ının nasıl ekleneceği gösterilmektedir:
Kotlin
// 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)
Java
// 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);
Yer tahminlerini programatik olarak alma
Uygulamanız, FindAutocompletePredictionsRequest
nesnesini ileterek PlacesClient.findAutocompletePredictions()
işlevini çağırarak tahmin edilen yer adlarının ve/veya adreslerin listesini otomatik tamamlama API'sinden 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 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ştururkensetQuery()
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ştururkensetTypesFilter()
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 deincludedRegionCodes
'ü belirtirseniz sonuçlar, iki ayarın kesişim alanında bulunur.countries parametresini ayarlamak için
FindAutocompletePredictionsRequest
nesnesini oluştururkensetCountries()
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ştururkensetInputOffset()
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ında olması gereken bölgeyi belirtme olarak düşünebilirsiniz. Aradaki temel fark, konum önyargısı olduğunda 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ştururkensetLocationBias()
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ştururkensetLocationRestriction()
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
vehigh
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 aşar).low.longitude
= -180 derece vehigh.longitude
= 180 derece ise görüntü alanı tüm boylamları içerir.low.longitude
= 180 derece vehigh.longitude
= -180 derece ise boylam aralığı boş olur.
Hem
low
hem dehigh
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ştururkensetOrigin()
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ştururkensetRegionCode()
yöntemini çağırın. -
Oturum jetonu
Oturum jetonları, hem widget aracılığıyla yapılan aramaları hem de programatik aramaları "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 göndermeli, ardından kullanıcı tarafından seçilen yerin yer ayrıntılarını almak içinfetchPlace()
çağrısında aynı jetonu bir yer kimliğiyle birlikte göndermelidir.Oturum jetonu parametresini ayarlamak için
FindAutocompletePredictionsRequest
nesnesini oluştururkensetSessionToken()
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ıldığı anlamına gelir. Bu durumda, belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumun çevresindeki sonuçlar döndürülebilir. 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 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çlarda "athletic_field"
gibi istemeyebileceğiniz türde tesisler bulunabilir.
Kaynağı kullanın
İ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 (Yeni) özelliğini 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.