Giriş
Otomatik tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının önceden yazma davranışını vermek için otomatik tamamlama özelliğini kullanabilirsiniz. Otomatik tamamlama hizmeti; yer adlarını, adresleri ve artı kodlarını çözümleyerek tam kelimeler ve alt dizelerle eşleşebilir. Bu nedenle uygulamalar, kullanıcı yazarken yer hakkında tahminlerde bulunmak için sorgu gönderebilir. Places API tarafından tanımlandığı gibi "yer", bir işletme, coğrafi konum veya önemli bir önemli yer olabilir.
Başlarken
Maps JavaScript API'de Yerler kitaplığını kullanmadan önce, ilk olarak Maps JavaScript API için ayarladığınız projede, Google Cloud Console'da Places API'nin etkinleştirildiğinden emin olun.
Etkin API'ler listenizi görüntülemek için:
- Google Cloud Console'a gidin.
- Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
- Kontrol Paneli'ndeki API listesinde Places API'yi bulun.
- API'yi listede görüyorsanız hazırsınız demektir. API listede yoksa etkinleştirin:
- Kitaplık sekmesini görüntülemek için sayfanın üst kısmında API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
- Places API'yi arayın ve ardından sonuçlar listesinden seçin.
- ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Places API görünür.
Kitaplık yükleniyor
Yerler hizmeti, ana Maps JavaScript API kodundan ayrı olan bağımsız bir kitaplıktır. Bu kitaplıkta bulunan işlevi kullanmak için öncelikle Maps API önyükleme URL'sindeki libraries
parametresini kullanarak işlevi yüklemeniz gerekir:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Daha fazla bilgi için Kitaplıklara Genel Bakış konusuna bakın.
Sınıfların özeti
API, sırasıyla Autocomplete
ve SearchBox
sınıfları aracılığıyla ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar.
Ayrıca, otomatik tamamlama sonuçlarını programlı bir şekilde almak için AutocompleteService
sınıfını kullanabilirsiniz (Haritalar JavaScript API Referansı: AutocompleteService sınıfı'na bakın).
Sunulan sınıfların özeti aşağıda verilmiştir:
-
Autocomplete
, web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişlerini izler. Kullanıcı metin girerken otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde, yerle ilgili bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz. -
SearchBox
,Autocomplete
ile aynı şekilde bir metin giriş alanı ekler. Farklılıklar aşağıdaki gibidir:- Temel fark, seçim listesinde görünen sonuçlardadır.
SearchBox
, yerlerin (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" ifadesini ve çeşitli pizza restoranlarının adlarını içerebilir. SearchBox
, aramayı kısıtlamak içinAutocomplete
seçeneğinden daha az seçenek sunar. Birincisinde, aramayı belirli birLatLngBounds
doğrulayacak şekilde ağırlıklandırabilirsiniz. İkinci kuralda, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve hem sınır belirleyebilirsiniz. Daha fazla bilgi için aşağıya bakın.
- Temel fark, seçim listesinde görünen sonuçlardadır.
- Tahminleri programatik olarak almak için
AutocompleteService
nesnesi oluşturabilirsiniz. Eşleşen yerleri almak içingetPlacePredictions()
numaralı telefonu arayın veya eşleşen yerleri ve önerilen arama terimlerini almak içingetQueryPredictions()
numaralı telefonu arayın. Not:AutocompleteService
herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, yukarıdaki yöntemler tahmin nesneleri dizisi döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgileri ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.
Otomatik Tamamlama widget'ı ekleme
Autocomplete
widget'ı web sayfanızda bir metin giriş alanı oluşturur, bir kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminleri sağlar ve bir getPlace()
isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş tek bir yere karşılık gelir (Places API tarafından tanımlandığı şekilde).
Autocomplete
kurucusu iki bağımsız değişken alır:
text
türünde bir HTMLinput
öğesi. Bu, otomatik tamamlama hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.- Aşağıdaki özellikleri içerebilen isteğe bağlı
AutocompleteOptions
bağımsız değişkeni:- Kullanıcının seçilen
PlaceResult
içinPlace Details
yanıtına dahil edilecekfields
veri dizisi. Mülk ayarlanmazsa veya['ALL']
geçirilirse mevcut tüm alanlar döndürülür ve faturalandırılır (bu, üretim dağıtımları için önerilmez). Alanların listesi içinPlaceResult
bölümüne bakın. - Desteklenen türlerde listelendiği şekliyle açık bir türü veya tür koleksiyonunu belirten bir
types
dizisi. Herhangi bir tür belirtilmezse tüm türler döndürülür. bounds
, yer aranacak alanı belirten birgoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırların içindeki yerlere ağırlık verir ancak bunlarla sınırlı değildir.strictBounds
, API'nin yalnızca belirtilenbounds
tarafından kesin olarak tanımlanan bölgeleri döndürmesinin gerekli olup olmadığını belirten birboolean
değeridir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışında sonuç döndürmez.- Sonuçları belirli gruplarla kısıtlamak için
componentRestrictions
kullanılabilir. Şu andacomponentRestrictions
kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak geçirilmelidir. Ülke kodu listesi olarak birden fazla ülke iletilmelidir.Not: Ülke koduyla birlikte beklenmedik sonuçlar alırsanız istediğiniz ülkeleri, bağımlı bölgeleri ve özel coğrafi bölgeleri içeren bir kod kullandığınızı doğrulayın. Kod bilgilerini Wikipedia: ISO 3166 ülke kodlarının listesi veya ISO Çevrimiçi Tarama Platformu'nda bulabilirsiniz.
placeIdOnly
,Autocomplete
widget'ına yalnızca Yer Kimliklerini alması talimatını vermek için kullanılabilir.Autocomplete
nesnesindegetPlace()
çağrılırken, kullanıma sunulanPlaceResult
için yalnızcaplace id
,types
vename
özellikleri ayarlanır. Döndürülen yer kimliğini Yerler, Coğrafi Kodlama, Yol Tarifleri veya Mesafe Matrisi hizmetlerine yapılan çağrılarda kullanabilirsiniz.
- Kullanıcının seçilen
Otomatik Tamamlama tahminlerini kısıtlama
Otomatik Yer Tamamlama, varsayılan olarak kullanıcının konumuna yakın tahminler için eğilimli olarak tüm yer türlerini sunar ve kullanıcının seçtiği yer için kullanılabilir tüm veri alanlarını getirir. Kullanım alanınıza dayalı olarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapım aşamasında seçenekleri belirleyin
Autocomplete
oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions
parametresi kabul eder. Aşağıdaki örnekte bounds
, componentRestrictions
ve types
seçenekleri, establishment
türü yerler isteğinde bulunacak şekilde ayarlanarak belirtilen coğrafi bölgedeki konumları tercih edecek ve tahminleri yalnızca ABD'deki yerlerle sınırlandıracak. fields
seçeneğinin ayarlanması, kullanıcının seçtiği yer hakkında hangi bilgilerin döndürüleceğini belirtir.
Mevcut bir widget'ta bir seçeneğin değerini değiştirmek için setOptions()
numaralı telefonu arayın.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
Veri alanlarını belirtin
İhtiyacınız olmayan Yer Verileri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya geçirilen AutocompleteOptions
içine fields
özelliğini ekleyin veya mevcut bir Autocomplete
nesnesinde setFields()
özelliğini çağırın.
autocomplete.setFields(["place_id", "geometry", "name"]);
Otomatik tamamlama için ağırlıkları ve arama alanı sınırlarını tanımlayın
Aşağıdaki yöntemleri kullanarak otomatik tamamlama sonuçlarına ağırlık vererek yaklaşık bir konum veya alanın lehine olmasını sağlayabilirsiniz:
Autocomplete
nesnesinin oluşturulmasıyla ilgili sınırları belirleyin.- Mevcut bir
Autocomplete
öğesinin sınırlarını değiştirin. - Sınırları haritanın görüntü alanına ayarlayın.
- Aramayı sınırlarla sınırlandırın.
- Aramayı belirli bir ülkeyle sınırlandırın.
Önceki örnekte, oluşturma sırasındaki sınırlar gösterilmektedir. Aşağıdaki örneklerde diğer ağırlık verme teknikleri gösterilmektedir.
Mevcut bir Otomatik tamamlamanın sınırlarını değiştirme
Mevcut bir Autocomplete
üzerindeki arama alanını dikdörtgen sınırlarla değiştirmek için setBounds()
çağrısı yapın.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Sınırları haritanın görüntü alanına göre ayarlayın
Görüntü alanı değişse bile sonuçları haritanın görüntü alanına göre ağırlık vermek için bindTo()
kullanın.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Otomatik tamamlama tahminlerinin haritanın görüntü alanından bağlantısını kaldırmak için unbind()
kısayolunu kullanın.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Aramayı geçerli sınırlarla kısıtlama
Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre geçerli sınırlara göre kısıtlamak için strictBounds
seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle sınırlama
Otomatik tamamlama aramasını en fazla beş ülkeden oluşan belirli bir grupla sınırlamak için componentRestrictions
seçeneğini kullanın veya setComponentRestrictions()
çağırın.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Yer türlerini sınırla
Tahminleri belirli yer türleriyle sınırlamak için types
seçeneğini kullanın veya setTypes()
yöntemini çağırın. Bu kısıtlama, Yer Türleri bölümünde listelendiği gibi bir türü veya tür koleksiyonunu belirtir.
Herhangi bir kısıtlama belirtilmezse tüm türler döndürülür.
types
seçeneğinin değeri veya setTypes()
öğesine iletilen değer için şunlardan birini belirtebilirsiniz:
Yer Türleri'nden Tablo 1 veya Tablo 2'den en fazla beş değer içeren bir dizi. Örneğin:
types: ['hospital', 'pharmacy', 'bakery', 'country']
veya:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Tablo 3'teki Yer Türleri kapsamındaki herhangi bir filtre. Tablo 3'ten yalnızca tek bir değer belirtebilirsiniz.
İstek şu durumlarda reddedilir:
- Beşten fazla tür belirtiyorsunuz.
- Tanınmayan türleri siz belirtirsiniz.
- Tablo 1 veya Tablo 2'deki türleri, Tablo 3'teki herhangi bir filtreyle karıştırabilirsiniz.
Yerler Otomatik Tamamlama demosu, farklı yer türleri arasındaki tahmin farklarını gösterir.
Yer bilgileri alınıyor
Kullanıcı otomatik tamamlama metin alanına eklenen tahminlerden bir yer seçtiğinde, hizmet bir place_changed
etkinliği tetikler. Yer ayrıntılarını almak için:
place_changed
etkinliği için bir etkinlik işleyici oluşturun ve işleyiciyi eklemek üzereAutocomplete
nesnesindeaddListener()
öğesini çağırın.PlaceResult
nesnesini almak içinAutocomplete
nesnesindeAutocomplete.getPlace()
çağırın. Bu nesneyi daha sonra seçilen yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.
Varsayılan olarak bir kullanıcı bir yer seçtiğinde otomatik tamamlama, seçilen yer için mevcut tüm veri alanlarını döndürür ve uygun şekilde faturalandırılır.
Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields()
değerini kullanın. İsteyebileceğiniz yer verisi alanlarının listesi de dahil olmak üzere PlaceResult
nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields()
kullandığınızdan emin olun.
name
özelliği, Yerler Otomatik Tamamlama tahminlerindeki description
öğesini içerir. description
hakkında daha fazla bilgiyi Yerler Otomatik Tamamlama dokümanlarında bulabilirsiniz.
Adres formları için adresi yapılandırılmış biçimde almak yararlıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields()
yöntemini çağırın ve address_components
alanını belirtin.
Aşağıdaki örnekte, bir adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmaktadır.
TypeScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
Yer tutucu metnini özelleştirme
Varsayılan olarak, otomatik tamamlama hizmeti tarafından oluşturulan metin alanı standart yer tutucu metin içerir. Metni değiştirmek için input
öğesinde placeholder
özelliğini ayarlayın:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Not: Varsayılan yer tutucu metin otomatik olarak yerelleştirilir. Kendi yer tutucu değerinizi belirtirseniz bu değerin yerelleştirilmesini uygulamanızda yapmanız gerekir. Google Maps JavaScript API'nin kullanılacak dili nasıl seçtiğiyle ilgili bilgi için lütfen yerelleştirme ile ilgili dokümanları okuyun.
Widget görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larının stilini belirleme başlıklı makaleye bakın.
Arama Kutusu widget'ı ekleme
SearchBox
, kullanıcıların "İstanbul'da pizza" veya "bostan yakınındaki ayakkabı mağazaları" gibi metne dayalı bir coğrafi arama gerçekleştirmelerine olanak tanır.
SearchBox
öğesini bir metin alanına ekleyebilirsiniz. Metin girildikçe hizmet, tahminleri açılır seçim listesi biçiminde döndürür.
SearchBox
, yerlerin (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" kelime öbeğinin yanı sıra çeşitli pizza restoranlarının adlarını içerebilir. Bir kullanıcı listeden bir yer seçtiğinde, bu yer hakkındaki bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.
SearchBox
kurucusu iki bağımsız değişken alır:
text
türünde bir HTMLinput
öğesi. Bu,SearchBox
hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.bounds
özelliğini içerebilen biroptions
bağımsız değişkeni:bounds
, yerlerin aranacağı alanı belirten birgoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırların içindeki yerlere ağırlık verir ancak bunlarla sınırlı değildir.
Aşağıdaki kodda, sonuçları enlem/boylam koordinatlarıyla belirtilen belirli bir coğrafi alandaki yerlere göre yönlendirmek için bounds parametresi kullanılır.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
Arama Kutusu için arama alanını değiştirme
Mevcut bir SearchBox
için arama alanını değiştirmek üzere SearchBox
nesnesinde setBounds()
çağrısı yapın ve ilgili LatLngBounds
nesnesini iletin.
Yer bilgileri alınıyor
Kullanıcı, arama kutusuna ekli tahminlerden bir öğe seçtiğinde hizmet bir places_changed
etkinliği tetikler. Her biri PlaceResult
nesnesi olan birkaç tahmin içeren bir dizi almak için SearchBox
nesnesinde getPlaces()
yöntemini çağırabilirsiniz.
PlaceResult
nesnesi hakkında daha fazla bilgi için
yer ayrıntısı sonuçları ile ilgili dokümanlara bakın.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
Widget görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larının stilini belirleme başlıklı makaleye bakın.
Yer Otomatik Tamamlama Hizmeti tahminlerini programlı olarak alma
Tahminleri programatik olarak almak için
AutocompleteService
sınıfını kullanın. AutocompleteService
, herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, her biri tahmin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir dizi tahmin nesnesi döndürür.
Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete
ve SearchBox
tarafından sunulandan daha fazla
denetime sahip olmak istiyorsanız yararlı olur.
AutocompleteService
aşağıdaki yöntemleri sunar:
getPlacePredictions()
yer tahminlerini döndürür. Not: "Yer", Places API tarafından tanımlandığı şekilde bir tesis, coğrafi konum veya önemli bir önemli yer olabilir.getQueryPredictions()
, yerleri (Places API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" kelime öbeğinin yanı sıra çeşitli pizza restoranlarının adlarını içerebilir.
Yukarıdaki yöntemlerin her ikisi de aşağıdaki biçimde bir tahmin nesneleri dizisi döndürür:
description
eşleşen tahmindir.distance_meters
, yerin belirtilenAutocompletionRequest.origin
ile arasındaki mesafenin metre cinsinden değeridir.matched_substrings
, açıklamada, kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içerir. Bu, uygulamanızda bu alt dizeleri vurgulamak için faydalıdır. Çoğu durumda sorgu, açıklama alanının bir alt dizesi olarak görünür.length
, alt dizenin uzunluğudur.offset
, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
place_id
, bir yeri benzersiz şekilde tanımlayan metin biçimli bir tanımlayıcıdır. Yer hakkında bilgi almak için bu tanımlayıcıyı Yer Ayrıntıları isteğininplaceId
alanına iletin. Yer kimliğiyle bir yeri referans gösterme hakkında daha fazla bilgi edinin.terms
, sorgunun öğelerini içeren bir dizidir. Bir yer için her öğe genellikle adresin bir bölümünü oluşturur.offset
, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.value
eşleşen terim.
Aşağıdaki örnekte, "yakında pizza" ifadesi için bir sorgu tahmini isteği yürütülmüştür ve sonuç bir listede görüntülenir.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p>Query suggestions for 'pizza near Syd':</p> <ul id="results"></ul> <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements --> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly" defer ></script> </body> </html>
Örneği Deneyin
Oturum jetonları
AutocompleteService.getPlacePredictions()
, otomatik tamamlama isteklerini faturalandırma amacıyla birlikte gruplandırmak için oturum jetonlarını (uygulandıysa) kullanabilir. Oturum jetonları, bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırı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 yapılabilir ve ardından tek bir yer seçimi yapılabilir.
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 otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken
parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, hiçbir oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).
Aynı oturum jetonunu, AutocompleteService.getPlacePredictions()
çağrısından kaynaklanan yer hakkında tek bir Yer Ayrıntıları isteği yapmak için kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve arama, normal Yer Ayrıntısı isteği olarak ücretlendirilir. Otomatik tamamlama isteği için ücret alınmaz.
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonu birden fazla Otomatik Tamamlama oturumunda kullanmak, bu Otomatik Tamamlama oturumlarını geçersiz kılar ve geçersiz oturumlardaki tüm Otomatik Tamamlama istekleri, İstek Başına Otomatik Tamamlama SKU'su kullanılarak ayrı ayrı ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.
Aşağıdaki örnekte, oturum jetonu oluşturulup ardından AutocompleteService
içinde gösterilmektedir (displaySuggestions()
işlevi kısa olması için atlanmıştır):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonu birden fazla oturumda kullanmak, her isteğin ayrı ayrı faturalandırılmasına neden olur.
Oturum jetonları hakkında daha fazla bilgi edinin.
Otomatik Tamamlama ve Arama Kutusu widget'larının stil özelliklerini ayarlama
Varsayılan olarak, Autocomplete
ve SearchBox
tarafından sağlanan kullanıcı arayüzü öğeleri, bir Google haritasına eklenmek üzere tasarlanmıştır. Stili kendi sitenize uyacak şekilde ayarlamak isteyebilirsiniz. Aşağıdaki CSS sınıfları kullanılabilir. Aşağıda listelenen tüm sınıflar, hem Autocomplete
hem de SearchBox
widget'ları için geçerlidir.
CSS sınıfı | Açıklama |
---|---|
pac-container |
Otomatik Yer Tamamlama hizmeti tarafından döndürülen tahminlerin listesini içeren görsel öğe. Bu liste, Autocomplete veya SearchBox widget'ının altında açılır liste olarak görünür. |
pac-icon |
Tahmin listesindeki her bir öğenin solunda gösterilen simge. |
pac-item |
Autocomplete veya SearchBox widget'ı tarafından sağlanan tahmin listesindeki bir öğe. |
pac-item:hover |
Kullanıcı fare imlecini üzerine getirdiğinde öğe. |
pac-item-selected |
Kullanıcı klavye aracılığıyla seçtiğinde öğe. Not: Seçilen öğeler, bu sınıfın ve pac-item sınıfının üyesi olacak.
|
pac-item-query |
Tahminin ana parçası olan pac-item içindeki bir aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "İstanbul'da pizza" gibi metin tabanlı aramalarda, sorgunun tam metnini içerir. Varsayılan olarak pac-item-query siyah renklidir. pac-item içinde ek metin varsa pac-item-query alanının dışındadır ve stilini pac-item öğesinden devralır. Varsayılan olarak gri renktedir. Ek metin genellikle bir adrestir. |
pac-matched |
Döndürülen tahminin, kullanıcı girişiyle eşleşen kısmı. Varsayılan olarak, bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin pac-item içinde herhangi bir yerde olabileceğini unutmayın. Bu, pac-item-query kapsamında olmayabilir ve kısmen pac-item-query içinde ve kısmen pac-item içindeki kalan metinde olabilir. |
Yer Seçici bileşenini kullanma
Not: Bu örnekte açık kaynak kitaplık kullanılmaktadır. Kitaplıkla ilgili destek ve geri bildirim için BENİOKU sayfasına göz atın.
Web bileşenlerini deneyin. Son kullanıcıların otomatik tamamlamayı kullanarak belirli bir adresi veya yeri aramasına olanak tanıyan metin girişini etkinleştirmek için Yer Seçici web bileşenini kullanın.
Otomatik Yer Tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Bazı genel yönergeler şunlardır:
- Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Otomatik tamamlama widget'ını, Android için Yerler SDK'sını Otomatik tamamlama widget'ını veya iOS için Yerler SDK'sını kullanmaktır. Otomatik tamamlama kullanıcı arayüzü kontrolü
- Otomatik Yer Tamamlama özelliğinin temel veri alanlarını daha en baştan anlayın.
- Konuma ağırlık verme ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkisi olabilir.
- API bir hata döndürürse uygulamanızın sorunsuz bir şekilde bozulmasını sağlamak için hata işlemeyi kullanın.
- Uygulamanızın hiçbir seçim olmadığında bunu karşıladığından ve kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.
Maliyet optimizasyonuyla ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetinin kullanım maliyetini optimize etmek için, yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larında alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına fiyatlandırmaya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Geocoding API sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığı takdirde, Coğrafi Kodlama API'si ile eşlenen İstek Başına fiyatlandırma, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
- Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntıları çağrısından daha azı için sunar.
- Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
Başvurunuz, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerektiriyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Uygulamanız; yer adı, iş durumu veya çalışma saatleri gibi Yer Ayrıntılarını gerektirdiğinden, Yer Otomatik Tamamlama özelliği, istekte bulunduğunuz yer verisi alanlarına bağlı olarak toplam 0, 017 ABD doları tutarında oturum başına ve geçerli Yer Verileri SKU'ları için bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak) kullanmalıdır.
Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields
parametresini belirttiğinizden emin olun.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları istenirken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Yer Tamamlama isteğinde kullanılan oturum jetonu
- İhtiyacınız olan yer veri alanlarını belirten
fields
parametresi
Hayır, yalnızca adres ve konum gerekiyor
Coğrafi Kodlama API'si, Yer Otomatik Tamamlama performansınıza bağlı olarak, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Otomatik Tamamlama verimliliği, kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların uygulanıp uygulanmadığına bağlı olarak değişiklik gösterir.
Aşağıdaki soruyu yanıtlamak için bir kullanıcının, uygulamanızda Otomatik Yer Tamamlama tahmini seçmeden önce ortalama kaç karakter girdiğini analiz edin.
Kullanıcılarınız ortalama olarak dört veya daha az istekte otomatik yer tamamlama tahminini seçiyor mu?
Evet
Otomatik Tamamlama özelliğini, oturum jetonları olmadan programlı bir şekilde uygulayın ve seçilen yer tahmini için Coğrafi Kodlama API'sini çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Otomatik Yer Tamamlama - İstek Başına isteği oluşturmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, seçilen yer tahminiyle ilgili olarak dört isteğin ve bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olacaktır. Bu, oturum başına 0,017 ABD doları olan Oturum Başına Otomatik Tamamlama fiyatından düşük olacaktır.1
Kullanıcılarınızın aradıkları tahmini daha da az karakterle elde etmelerine yardımcı olmak için performans en iyi uygulamalarından yararlanabilirsiniz.
Hayır
Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Kullanıcılar bir Otomatik Yer Tamamlama tahminini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Yer Otomatik Tamamlama özelliği hem Yer Otomatik Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu (oturum başına toplam 0,017 ABD doları) kullanmalıdır.1
Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields
parametresini belirttiğinizden emin olun.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları istenirken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Yer Tamamlama isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veri alanlarını belirten
fields
parametresi
Yer Otomatik Tamamlama isteklerini geciktirmeyi düşünün
Bir Yer Otomatik Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejilerden yararlanarak uygulamanızın daha az istekte bulunmasını sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteklerinde bulunmak, kullanıcı yedi karakter yazıp ardından bir Coğrafi Kodlama API'sı isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 ABD Doları + 0,005 Coğrafi Kodlama ABD doları).1
Geciken istekler, ortalama programatik isteğinizi dörde dörde alabiliyorsa Geocoding API ile iyi performans gösteren Yer Otomatik Tamamlama uygulamasıyla ilgili yönergeleri izleyebilirsiniz. Geciken isteklerin, her yeni tuş vuruşunda tahmin 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 yararlanmayı düşünün.
-
Burada listelenen maliyetler ABD doları cinsindendir. Tam fiyatlandırma bilgileri için lütfen Google Haritalar Platformu Faturalandırması sayfasına bakın.
Performansla ilgili en iyi uygulamalar
Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansını optimize etme yöntemleri açıklanmaktadır:
- Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, yere ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtiği için dil tercihi gerekli değildir.
- Otomatik Yer Tamamlama'ya bir harita eşlik ediyorsa, konumu harita görünümüne göre yönlendirebilirsiniz.
- Kullanıcının Otomatik tamamlama tahminlerinden birini seçmediği durumlarda (genellikle bu tahminlerin hiçbiri istenen sonuç adresi olmadığından), daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
- Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API'ye yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
- Kullanıcının ada veya adrese göre belirli bir yer için sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuçlar bekleniyorsa konuma ağırlık vermeyi kullanın.
- Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin tamamlanmadığı ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresi giren kullanıcılar. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
- New York'ta "23-30 29
Kullanım sınırları ve politikaları
Kotalar
Kota ve fiyatlandırma bilgileri için Places API'nin Kullanım ve Faturalandırma belgelerine bakın.
Politikalar
Yerler Kitaplığı ve Maps JavaScript API'nin kullanımı, Place API'si için açıklanan politikalara uygun olmalıdır.