Autocomplete (New), 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 tam kelimeleri ve alt dizeleriyle eşleşerek yer adlarını, adresleri ve Plus Code'ları çözebilir. Uygulamanız, kullanıcı yazarken sorgu göndererek anında yer ve sorgu tahminleri sunabilir.
Örneğin, Autocomplete'i çağırırken giriş olarak kısmi kullanıcı girişi içeren bir dize ("Sicilya piz") kullanırsınız ve arama alanını San Francisco, Kaliforniya ile sınırlarsınız. Yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesini (ör. "Sicilian Pizza Kitchen" adlı restoran) içerir. Döndürülen yer tahminleri, kullanıcıya sunulmak ve 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 temel yöntemle entegre edebilirsiniz:
- Yer Adı Otomatik Tamamlama widget'ını ekleyin: Kullanıcı yazarken tahminleri gösteren
PlaceAutocompletesınıfı aracılığıyla kullanıma 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 Adı Otomatik Tamamlama deneyimini daha kolay sunmak için uygulamanıza Yer Adı Otomatik Tamamlama widget'ını ekleyebilirsiniz. Widget, kullanıcı girişini işleyen ve kullanıcıya yer tahminlerini gösterirken uygulamaya AutocompletePrediction nesneleri döndüren ö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ğ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:
(İsteğe bağlı) Bir 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
autocompleteIntenttanımlayın.StartActivityForResultiçinActivityResultLaunchertanımlayın. Bu başlatıcı, otomatik tamamlama etkinliğinden döndürülen sonucu işler.Sonucu
ActivityResultLaunchergeri çağırma işlevinde işleyin. Bu işlem,AutocompletePredictionveAutocompleteSessionToken(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çinfetchPlace()isteği göndermeyi içerir.placeAutocompleteActivityResultLauncherkullanarak intent'i başlatın.
Aşağıdaki örneklerde, hem Kotlin hem de Java kullanarak Yer Adı 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);
Temayı özelleştirme
Bir 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, aralığını, kenarlıklarını ve köşelerini özelleştirebilirsiniz. Varsayılan değer:
PlacesMaterialTheme. Geçersiz kılınmayan tema özellikleri, varsayılan stilleri kullanır.
…/res/values/themes.xml politikasında 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>
Ardından, setAutocompleteUiCustomization yöntemini çağırarak 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. Sorgu ve filtre ölçütleriyle eşleşen 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,CharacterStylekullanarak açıklamanın aramayla eşleşen bölümlerini istediğiniz bir stille vurgulamanıza olanak tanır.CharacterStyleparametresi isteğe bağlıdır. Vurgulama gerekmiyorsa 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 "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, 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 tanımlayıcıyı kullanarakPlacenesnesini daha sonra tekrar alabilirsiniz. Otomatik tamamlama özelliğindeki 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
Aranacak metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve Plus Code'ları belirtin. Otomatik Tamamlama (Yeni) 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 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'deki tür değerlerinden en fazla beş tanesini içeren liste. 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'deki türlerden 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 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ı dahil edin. Bu liste, en fazla 15 adet 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ştiği alanda yer alır.
Ülke 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ğu kullanılır.
Giriş ofseti parametresini ayarlamak için FindAutocompletePredictionsRequest nesnesini oluştururken setInputOffset() yöntemini çağırın.
Konum tercihi 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. Temel fark, konuma dayalı tercihte belirtilen bölgenin dışındaki sonuçların da döndürülebilmesidir.
Konum yanlılığı
Arama yapılacak alanı belirtir. Bu konum bir kısıtlama değil, yanlılık olarak kullanılır. Bu nedenle, belirtilen alanın dışındaki sonuçlar da döndürülebilir.
Konum tercihi parametresini ayarlamak için
FindAutocompletePredictionsRequestnesnesini oluştururkensetLocationBias()yöntemini çağırın.Konum kısıtlaması
Arama yapılacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez.
Konum kısıtlama parametresini ayarlamak için
FindAutocompletePredictionsRequestnesnesini oluştururkensetLocationRestriction()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, çapraz olarak karşılıklı iki
lowvehighnoktası 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ı 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=highise görüntü alanı bu tek noktadan oluşur.low.longitude>high.longitudeise boylam aralığı ters çevrilir (görüntü alanı 180 derece boylam çizgisini geçer).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ştur.
Hem
lowhem dehighdoldurulmalıdır ve temsil edilen kutu boş olamaz. Boş bir görüntü alanı hataya neden olur.
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 bölge kodu. ccTLD ("üst düzey alan") iki karakterli değeri olarak belirtilir. Çoğu ccTLD kodu, 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) 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ı, Autocomplete (New) çağrılarını (hem widget üzerinden yapılan çağrılar hem de programatik çağrılar) "oturum" olarak izleyen, kullanıcı tarafından oluşturulan dizelerdir. Otomatik tamamlama, faturalandırma amacıyla bir 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 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ça 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 iletmelidir. Ardından, kullanıcının seçtiği 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
Autocomplete (New), arama alanını kontrol etmek için varsayılan olarak IP yönlendirmesini kullanır. IP'ye dayalı 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 merkezli 5.000 metrelik yarıçapa sahip 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 tercihi kullanıldığında konum, tercih olarak kullanılır. Bu, belirtilen konumun çevresindeki sonuçların (belirtilen alanın dışındaki sonuçlar dahil) döndürülebileceği anlamına gelir. Aşağıdaki örnekte, önceki istek konum tercihi kullanılacak ş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ürle kısıtlamak 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 belirtilmekte ve sonuçları "sporting_goods_store" türündeki işletmelerle 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 atlarsanız sonuçlar, istemediğiniz türde (ör. "athletic_field") 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, Maps JavaScript API Otomatik Tamamlama (Yeni) widget'ını, Android için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını veya iOS için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını kullanmaktır.
- Temel Otomatik Tamamlama (Yeni) 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 bir hata döndürürse uygulamanızın düzgün bir şekilde çalışmaya devam etmesi için hata işleme özelliğini 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
Autocomplete (New) hizmetini kullanma maliyetini optimize etmek için Yer Ayrıntıları (New) ve Autocomplete (New) widget'larında alan maskeleri kullanarak yalnızca ihtiyacınız olan Autocomplete (New) veri alanlarını döndürün.
Gelişmiş maliyet optimizasyonu
SKU: Autocomplete Request fiyatlandırmasına erişmek ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçları istemek için Autocomplete'in (Yeni) programatik uygulamasını kullanabilirsiniz. Geocoding API ile eşlenen istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılandığında oturum başına (oturum tabanlı) fiyatlandırmadan 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ın ihtiyaç duyduğu izinler | Kullanıcı bir tahmin seçmeden önce ortalama Otomatik Tamamlama (Yeni) isteği sayısı | Önerilen uygulama |
|---|---|---|
| Adres ve konum dışındaki yer ayrıntıları (ör. yer adı, işletme durumu veya çalışma saatleri) | Herhangi bir sayıda | Yer Ayrıntıları (Yeni) ile oturum tabanlı Otomatik Tamamlama (Yeni) |
| Yalnızca seçilen tahminin adresi ve enlem/boylamı | Dört veya daha az | Geocoding API ile istek başına Autocomplete (New) |
| Yalnızca seçilen tahminin adresi ve enlem/boylamı | Dörtten fazla | Yalnızca adres uygulamaları için oturum tabanlı Autocomplete (New) |
Geocoding API, Autocomplete (New) kullanımınızın performansına bağlı olarak uygulamanız için Yer Ayrıntıları (New)'dan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Autocomplete (New) verimliliği; kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların hayata geçirilip geçirilmediğine bağlı olarak değişir.
Tablo için ortalama istek sayısını bulmak istiyorsanız uygulamanızda bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce kullanıcının ortalama kaç karakter yazdığını analiz edin.
Yer Ayrıntıları (Yeni) ile oturuma dayalı Otomatik Tamamlama (Yeni)
Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları (Yeni) bilgilerini gerektirdiğinden Otomatik Tamamlama (Yeni) uygulamanızda, istediğiniz yer veri alanlarına bağlı olarak oturum başına bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larına yerleşik olarak) ve geçerli Places SKU'ları kullanılmalıdır.1
Widget uygulaması
Oturum yönetimi;
JavaScript,
Android
veya iOS
widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan Autocomplete (New) veri alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.
Programatik uygulama
Otomatik Tamamlama (Yeni) isteklerinizde
oturum jetonu
kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
- Autocomplete (New) isteğinde kullanılan oturum jetonu
- İhtiyacınız olan Otomatik Tamamlama (Yeni) veri alanlarını belirten
fieldsparametresi
Geocoding API ile istek başına Autocomplete (New)
Autocomplete'i (New) oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını sağlar.
Dört Autocomplete Requests isteği ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısı yapmanın maliyeti, oturum başına Autocomplete (New) maliyetinden daha düşüktür.1
Kullanıcılarınızın aradıkları tahmini daha az karakterle almalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
Yalnızca adres uygulamaları için oturuma dayalı Autocomplete (New)
Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Kullanıcı bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırma maliyetini aştığından Otomatik Tamamlama (Yeni) uygulamanızda hem Otomatik Tamamlama (Yeni) istekleri hem de ilişkili Yer Ayrıntıları (Yeni) isteği için oturum jetonu kullanılmalıdır.
oturum başına.
1
Widget uygulaması
Oturum yönetimi;
JavaScript,
Android
veya iOS
widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan alanları istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.
Programatik uygulama
Autocomplete (New) isteklerinizde
oturum jetonu
kullanın.
Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
- Autocomplete (New) isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi alanları belirten
fieldsparametresi
Autocomplete (New) isteklerini geciktirmeyi düşünün
Uygulamanızın daha az istek göndermesi için Autocomplete (New) isteğini kullanıcı ilk üç veya dört karakteri yazana kadar geciktirme gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Autocomplete (New) istekleri yapılması, kullanıcı yedi karakter yazıp ardından bir Geocoding API isteği yaptığınız bir tahmini seçerse toplam maliyetin 4 Autocomplete (New) istek başına + Geocoding için olacağı anlamına gelir.1
İstekleri geciktirmek ortalama programatik istek sayınızı dörtten az yapabiliyorsa Geocoding API ile yüksek performanslı Autocomplete (New) uygulamasıyla ilgili kılavuzu takip edebilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahminleri görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.
Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
-
Maliyetler için Google Haritalar Platformu fiyat listelerine bakın.
Performansla ilgili en iyi uygulamalar
Aşağıdaki yönergelerde, Otomatik Tamamlama (Yeni) performansını optimize etme yöntemleri açıklanmaktadır:
- Otomatik Tamamlama (Yeni) uygulamanıza ülkeye özgü kısıtlamalar, konum ağırlığı ve (programatik uygulamalar için) dil tercihleri ekleyin. Widget'lar, dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından aldığı için widget'larda dil tercihine gerek yoktur.
- Autocomplete (New) ile birlikte bir harita varsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
- Kullanıcı, Autocomplete (New) tahminlerinden birini seçmediğinde (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
- Kullanıcının yalnızca adres bilgisi 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ığı kullanın.
- Kullanıcılar, bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini giriyor. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Tamamlama (Yeni) özelliğinde kısmi bir tahmin döndürür.
- 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.
Konuma göre yönlendirme
location parametresi ve radius parametresi ileterek sonuçları belirli bir alana göre önceliklendirin. 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 kısıtlayın.
Ayrıca, locationRestriction parametresini ekleyerek sonuçları location ve radius parametresiyle tanımlanan bölgeyle kısıtlayabilirsiniz. Bu, Otomatik Tamamlama'ya (Yeni) yalnızca bu bölgedeki sonuçları döndürmesini söyler.