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ı sağlamak için otomatik tamamlama özelliğini kullanabilirsiniz. Otomatik tamamlama hizmeti; yer adları, adresler ve artı kodları çözümlenerek tam kelimeler ve alt dizelerle eşleşebilir. Böylece uygulamalar, anında yer tahminleri sağlamak için kullanıcı yazarken sorgu gönderebilir.
Kullanmaya başlama
Maps JavaScript API'de Yerler kitaplığını kullanmadan önce, ilk olarak Maps JavaScript API için oluşturduğunuz 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 arayın.
- Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
- Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
- Places API'yi arayın ve 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 yer alan işlevi kullanmak için önce Maps API önyükleme URL'sindeki libraries
parametresini kullanarak bu işlevi yüklemeniz gerekir:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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şleri için izler. Kullanıcı metin girdiğinde otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde, bu 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.Şekil 1: Metin alanını ve seçim listesini otomatik doldurma Şekil 2: Doldurulmuş adres formu -
SearchBox
,Autocomplete
ile hemen hemen aynı şekilde bir metin giriş alanı ekler. Farklar aşağıda belirtilmiştir:- Başlıca fark, seçim listesinde gösterilen sonuçlardadır.
SearchBox
, yerleri (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 bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizza şubelerinin adları yer alabilir. SearchBox
, aramayı kısıtlamak içinAutocomplete
seçeneğinden daha az seçenek sunar. Birincisinde, aramayı belirli birLatLngBounds
değerine göre yönlendirebilirsiniz. İkinci seçenekte, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıdaki bilgilere göz atın.
Şekil 3: Arama Kutusu arama terimleri ve yer tahminleri sunar. - Başlıca fark, seçim listesinde gösterilen 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ü denetimi eklemez. Bunun yerine, yukarıdaki yöntemler bir dizi tahmin nesneleri 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, kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminleri sağlar ve getPlace()
isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her bir 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ı bir
AutocompleteOptions
bağımsız değişkeni:- Kullanıcının seçilen
PlaceResult
içinPlace Details
yanıtına dahil edilecekfields
veri dizisi. Özellik ayarlanmazsa veya['ALL']
aktarılırsa kullanılabilir tüm alanlar döndürülür ve ücretlendirilir (bu, üretim dağıtımları için önerilmez). Alanların listesi içinPlaceResult
bölümünü inceleyin. - Desteklenen türlerde listelendiği gibi açık bir türü veya tür koleksiyonunu belirten bir
types
dizisi. Tür belirtilmezse tüm türler döndürülür. bounds
, yerlerin aranacağı alanı belirten birgoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırların içindeki yerlere yönlüdür, ancak bunlarla sınırlı değildir.strictBounds
, API'nin yalnızca belirtilenbounds
ile tanımlanan bölgede bulunan yerleri döndürmesi gerekip gerekmediğini belirten birboolean
öğesidir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışındaki sonuçları döndürmez.componentRestrictions
, sonuçları belirli gruplarla kısıtlamak için kullanılabilir. Şu andacomponentRestrictions
kullanarak en fazla 5 ülkeye göre filtreleyebilirsiniz. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Ülke kodlarının bir listesi olarak birden çok ülke iletilmelidir.Not: Ülke koduyla birlikte beklenmedik sonuçlar alırsanız hedeflediğ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
yalnızcaplace id
,types
vename
özellikleri ayarlanır. Döndürülen yer kimliğini Yerler, Coğrafi Kodlama, Yol Tarifi veya Mesafe Matrisi hizmetlerine yapılan çağrılarda kullanabilirsiniz.
- Kullanıcının seçilen
Otomatik Tamamlama tahminlerini kısıtlama
Varsayılan olarak Yer Otomatik Tamamlama, kullanıcının bulunduğu konumun yakınındaki tahminler için eğilimli olacak şekilde tüm yer türlerini sunar ve kullanıcının seçtiği yer için mevcut 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
parametresini kabul eder. Aşağıdaki örnekte, establishment
türü yerler istemek için bounds
, componentRestrictions
ve types
seçenekleri belirtilmektedir. Bu seçenekler, belirtilen coğrafi bölgedeki yerler için tercih edilir ve tahminleri yalnızca ABD içindeki yerlerle sınırlandırılır. fields
seçeneğinin ayarlanması, kullanıcının seçilen yerle ilgili 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ı belirtme
İhtiyacınız olmayan Yer Verileri SKU'ları için faturalandırılmamak üzere veri alanları belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions
öğesine fields
özelliğini ekleyin veya mevcut bir Autocomplete
nesnesinde setFields()
yöntemini ç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ında yaklaşık bir konuma veya alana öncelik verebilirsiniz:
Autocomplete
nesnesinin oluşturulması sırasında sınırları ayarlayın.- 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 ayar 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()
işlevini çağırı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 ayarlayın
Söz konusu görüntü alanı değişse bile sonuçları haritanın görüntü alanına göre
yönlendirmek için bindTo()
kullanın.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Haritanın görüntü alanındaki Otomatik Tamamlama tahminlerinin bağlantısını kaldırmak için unbind()
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 sınırla
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ı beş taneye kadar ülke içeren belirli bir grupla sınırlamak için componentRestrictions
seçeneğini kullanın veya setComponentRestrictions()
numaralı telefonu ç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 koleksiyonu 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 aşağıdakilerden 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'ndeki herhangi bir filtre. Tablo 3'ten yalnızca tek bir değer belirtebilirsiniz.
İstek aşağıdaki durumlarda reddedilir:
- Beşten fazla tür belirtiyorsunuz.
- Tanınmayan türleri belirtirsiniz.
- Tablo 1 veya Tablo 2'deki herhangi bir türü, Tablo 3'teki herhangi bir filtreyle birlikte kullanabilirsiniz.
Yerler Otomatik Tamamlama demosu, farklı yer türleri arasında yapılan tahminler arasındaki farkları 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()
değerini çağırın.Autocomplete
nesnesindeAutocomplete.getPlace()
yöntemini çağırarakPlaceResult
nesnesini alın. Daha sonra bu nesneyi 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 buna göre faturalandırılırsınız.
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 tahminlerinden gelen description
bilgisini 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 faydalıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields()
değerini ç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 metni ö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ği hakkında 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 konusuna bakın.
Arama Kutusu widget'ı ekleme
SearchBox
, kullanıcıların "İstanbul'da pizza" veya "İzmir Caddesi'ndeki ayakkabı mağazaları" gibi metne dayalı bir coğrafi arama gerçekleştirmesine 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
, yerleri (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 bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizzacıların adları yer alabilir. 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ı belirtengoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırların içindeki yerlere dayalı olup bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları enlem/boylam koordinatlarıyla belirtilen belirli bir coğrafi alandaki yerlere göre ağırlıklandırmak için bounds parametresini kullanı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 });
SearchBox için arama alanını değiştirme
Mevcut bir SearchBox
öğesinin arama alanını değiştirmek için SearchBox
nesnesinde setBounds()
çağrısı yapın ve ilgili LatLngBounds
nesnesini iletin.
Yer bilgileri alınıyor
Kullanıcı, arama kutusuna eklenen tahminlerden bir öğe seçtiğinde hizmet bir places_changed
etkinliği tetikler. Her biri PlaceResult
nesnesi olan çeşitli tahminler içeren bir dizi almak için SearchBox
nesnesinde getPlaces()
çağırabilirsiniz.
PlaceResult
nesnesi hakkında daha fazla bilgi için
yer ayrıntısı sonuçları hakkındaki 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 konusuna bakın.
Otomatik Yer Tamamlama Hizmeti tahminlerini programatik 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 tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir tahmin nesneleri dizisi döndürür.
Kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete
ve SearchBox
tarafından sunulandan daha fazla kontrol sahibi olmak istiyorsanız bu yöntem yararlıdır.
AutocompleteService
aşağıdaki yöntemleri sunar:
getPlacePredictions()
yer tahminlerini döndürür. Not: "Yer", Places API tarafından tanımlandığı şekliyle bir işletme, coğrafi konum veya önemli bir yer olabilir.getQueryPredictions()
, yerleri (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "pizza in new" yazarsa seçim listesinde "pizza in New York, NY" ifadesi ve çeşitli pizza restoranlarının adları yer alabilir.
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, bu alt dizeleri uygulamanızda vurgulamak için kullanışlıdır. Sorgu, çoğu durumda 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 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
, sorgu öğ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, "pizza yakınındaki" kelime öbeği 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> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <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 callback 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()
, faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonları kullanır. Oturum jetonları, kullanıcının otomatik tamamlama özelliğinin 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 bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir.
Bir oturum sonlandırıldıktan sonra 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 jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).
AutocompleteService.getPlacePredictions()
öğesine yapılan bir çağrıdan kaynaklanan yer hakkında tek bir Yer Ayrıntıları isteği göndermek için aynı oturum jetonunu kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntısı 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 aktardığınızdan emin olun. Aynı jetonu birden fazla Otomatik Tamamlama oturumu için 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 tek tek ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.
Aşağıdaki örnekte, bir oturum jetonu oluşturulup daha sonra AutocompleteService
içinde iletilmesi 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 aktardığınızdan 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, Google haritasına eklenmek üzere tasarlanmıştır. Stili kendi sitenize uygun şekilde ayarlayabilirsiniz. Aşağıdaki CSS sınıfları mevcuttur. 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 bir 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ı klavyeyle 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. pac-item-query varsayılan olarak 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 renklidir. Ek metin genellikle bir adrestir. |
pac-matched |
Döndürülen tahminin kullanıcı girişiyle eşleşen bölümü. Varsayılan olarak, bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin, pac-item sınırları içinde herhangi bir yerde olabileceğini unutmayın. Bu ülke mutlaka pac-item-query kapsamında olmayabilir ve hem pac-item-query içinde hem de kısmen pac-item içinde kalan metnin içinde olabilir. |
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.
Aşağıda bazı genel yönergeler verilmiştir:
- Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu; Maps JavaScript API Otomatik tamamlama widget'ı, Android için Yerler SDK'sı Otomatik tamamlama widget'ı veya iOS için Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü kullanmaktır.
- Otomatik Yer Tamamlama veri alanlarıyla ilgili temel bilgileri en baştan geliştirin.
- Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlı olsa da otomatik tamamlama performansı üzerinde önemli etkileri olabilir.
- API hata döndürürse uygulamanızın sorunsuz bir şekilde eskimesini sağlamak için hata işlemeyi kullanın.
- Uygulamanızın seçim olmadığında işlemleri 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 hizmetini kullanma 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ırma'ya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'sı sonuçlarını istemek için Yer Otomatik Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen İstek Başına fiyatlandırması, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
- Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir tutar için sağlar.
- 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şvurunuzda, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerekiyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Uygulamanız; yer adı, işletmenin durumu veya çalışma saatleri gibi Yer Ayrıntıları gibi yer ayrıntıları gerektirdiğinden, Otomatik Yer Tamamlama uygulamanızda, hangi yer verisi alanlarına bağlı olarak 0, 017 ABD doları tutarında oturum başına ve geçerli Yer Veri SKU'ları'nın toplam maliyetine sahip olmak üzere bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunur) kullanılmalıdır33}{/14
Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. 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 belirtmeyi unutmayın.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Tamamlama isteğinde kullanılan oturum jetonu
- İhtiyacınız olan yer verisi alanlarını belirten
fields
parametresi
Hayır, yalnızca adres ve konum gerekir
Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak, Coğrafi Kodlama API'si, 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 optimizasyonu en iyi uygulamalarını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 bir Otomatik Yer Tamamlama tahmini seçmeden önce ortalama kaç karakter girdiğini analiz edin.
Kullanıcılarınız ortalama dört veya daha az istekte Otomatik Yer Tamamlama tahminini seçiyor mu?
Evet
Otomatik Yer Tamamlama özelliğini, oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde 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 Yer Otomatik Tamamlama - İstek Başına isteğinin maliyeti 0,01132 ABD dolarıdır. Dolayısıyla, dört isteğin ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu, oturum başına 0,017 ABD doları tutarındaki Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.1
Kullanıcılarınızın aradıkları tahmini daha da az karakterle bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
Hayır
Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Kullanıcılar bir Otomatik Yer Tamamlama tahmini seçmeden önce yapılmasını beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama istekleriniz hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanmalıdır.Bu durumda, oturum başına toplam 0,017 ABD doları maliyet elde edilir.1
Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. 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 belirtmeyi unutmayın.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Tamamlama isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veriler alanlarını belirten
fields
parametresi
Otomatik Yer Tamamlama isteklerini ertelemeyi düşünün
Uygulamanızın daha az istek yapması için Otomatik Yer Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejilerden yararlanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Yer Tamamlama isteklerinde bulunmak, kullanıcı yedi karakter yazıp bir Coğrafi Kodlama API'si isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 Otomatik Tamamlama + 0,005 Coğrafi Kodlama ABD doları).1
Geciken istekler, ortalama programatik isteğinizi dörde düşmesine neden oluyorsa Coğrafi Kodlama API'si ile performans gösteren Yer Otomatik Tamamlama uygulaması için yönergeleri uygulayabilirsiniz. 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 yararlanabilirsiniz.
-
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ı, konuma 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ğinden, dil tercihi gerekli değildir.
- Otomatik Yer Tamamlama'yı bir harita içeriyorsa, konumu harita görüntü alanına göre taşıyabilirsiniz.
- Kullanıcının Otomatik Tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden 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 çağrısında orijinal kullanıcı girişini yeniden kullanın.
- Kullanıcının belirli bir yer için ad veya adrese göre sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
- Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresleri giren kullanıcılar. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Yer Tamamlama'da kısmi bir tahmin sağlar.
- 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 için açıklanan politikalara uygun olmalıdır.