Giriş
Otomatik tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanında arama türü davranışını vermek için otomatik tamamlama özelliğini kullanabilirsiniz. Otomatik tamamlama hizmeti; tam kelimeler ve alt dizelerle eşleşerek yer adlarını, adresleri ve artı kodlarını çözebilir. Bu nedenle uygulamalar, anında yer tahminleri sağlamak için kullanıcı türü olarak sorgu gönderebilir.
Kullanmaya başlama
Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce, Yerler API'sinin Google Cloud Console'da etkinleştirilmiş olduğundan emin olun. Bu işlem, Maps JavaScript API için ayarladığınız projede gerçekleşir.
Etkin API'lerinizin listesini 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ındaki API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak sol taraftaki menüden Kitaplık'ı seçin.
- Places API'yi arayıp sonuçlar listesinden seçin.
- ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Places API, Kontrol Paneli'nde API listesinde görünür.
Kitaplık yükleniyor
Rehber hizmeti, ana Maps JavaScript API kodundan ayrı, bağımsız bir kitaplıktır. Bu kitaplıkta bulunan işlevi kullanmak için önce Haritalar API'si ö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&libraries=places&callback=initMap">
</script>
Daha fazla bilgi için Kitaplıklara Genel Bakış sayfasını inceleyin.
Sınıfların özeti
API, iki tür otomatik tamamlama widget'ı sunar. Bu widget'ları sırasıyla Autocomplete
ve SearchBox
sınıfları aracılığıyla ekleyebilirsiniz.
Ayrıca, otomatik tamamlama sonuçlarını programlı şekilde almak için AutocompleteService
sınıfını da kullanabilirsiniz (Haritalar JavaScript API Referansı'na bakın: AutocompleteService class).
Aşağıda, kullanılabilen sınıfların özetini bulabilirsiniz:
-
Autocomplete
web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metni girdikçe otomatik tamamlama, yer tahminlerini bir açılır liste listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde bu yer hakkındaki 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ı otomatik tamamlama ve liste seçme Şekil 2: Adres formunu doldurdu -
SearchBox
, web sayfanızaAutocomplete
ile hemen hemen aynı bir metin giriş alanı ekler. Farklar aşağıda belirtilmiştir:- Aradaki temel fark, seçim listesinde gösterilen sonuçlardır.
SearchBox
, yerler (Yerler API'si tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'daki pizzacı" kelime öbeğini ve çeşitli pizzacıların adlarını içerebilir. SearchBox
, aramayı kısıtlamak içinAutocomplete
değerinden daha az seçenek sunar. Birincisinde, belirli birLatLngBounds
ile ilgili arama yapılmasına önyargılı olabilirsiniz. Sonuncusunda, sınırları belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve sınırlandırabilirsiniz. Daha fazla bilgi için aşağıya bakın.
Şekil 3: Arama Kutusu, arama terimleri ve yer tahminleri sunar. - Aradaki temel fark, seçim listesinde gösterilen sonuçlardır.
- Tahminleri programatik olarak almak için bir
AutocompleteService
nesnesi oluşturabilirsiniz. Eşleşen yerleri almak içingetPlacePredictions()
yöntemini 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 bir dizi tahmin nesnesi döndürür. Her tahmin nesnesi, tahminin 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 tahminlerde bulunur 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 (Places API tarafından tanımlandığı şekilde) karşılık gelir.
Autocomplete
oluşturucu, 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çtiği
PlaceResult
içinPlace Details
yanıtına dahil edilecek birfields
veri dizisi. Özellik ayarlanmazsa veya['ALL']
aktarılırsa kullanılabilir 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
adresini ziyaret edin. - Desteklenen türlerde listelendiği şekliyle, açık bir türü veya tür koleksiyonunu belirten
types
dizisi. Herhangi bir tür belirtilmezse tüm türler döndürülür. bounds
, içinde arama yapılacak alanı belirten birgoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere doğrudur, ancak bunlarla sınırlı değildir.strictBounds
, API'nin yalnızca belirlibounds
tarafından tanımlanan bölgede bulunan yerleri döndürmesi gerekip gerekmediğini belirten birboolean
'dir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışında sonuç döndürmez.componentRestrictions
, sonuçları belirli gruplarla kısıtlamak için kullanılabilir. Şu andacomponentRestrictions
kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu bir ülke kodu olarak geçirilmelidir. Ülke kodu listesi olarak birden fazla ülke belirtilmelidir.Not: Bir ülke koduyla beklenmeyen sonuçlar alırsanız ülkeleri, bağımlı bölgeleri ve hedeflediğiniz coğrafi ilgi alanlarının yer aldığı bir kod kullandığınızdan emin olun. Kod bilgilerini Wikipedia: ISO 3166 ülke kodlarının listesi veya ISO Online Tarama Platformu'nda bulabilirsiniz.
placeIdOnly
,Autocomplete
widget'ına yalnızca Yer Kimliklerini alma talimatı vermek için kullanılabilir.Autocomplete
nesnesindegetPlace()
çağrılırken, kullanılabilir olanPlaceResult
öğesine yalnızcaplace id
,types
vename
özellikleri ayarlanır. Döndürülen yer kimliğini Yerler, Coğrafi Kodlama, Yol Tarifi veya Mesafe Matrisi çağrılarıyla kullanabilirsiniz.
- Kullanıcının seçtiği
Otomatik tamamlama tahminlerini kısıtlama
Varsayılan olarak, otomatik yer doldurma işlevi tüm konum türlerini sunar, kullanıcının bulunduğu yerin yakınındaki tahminlere ağırlık verir ve kullanıcının seçtiği yer için mevcut tüm veri alanlarını getirir. Kullanım alanınıza göre daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapım aşamasındaki seçenekleri ayarlama
Autocomplete
oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions
parametresi kabul eder. Aşağıdaki örnekte, establishment
türü yer isteğinde bulunmak için belirtilen bounds
, componentRestrictions
ve types
seçenekleri belirlenerek belirtilen coğrafi bölgedekiler tercih ediliyor ve tahminler yalnızca ABD'deki yerlerle sınırlanıyor. 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 için bir seçeneğin değerini değiştirmek üzere setOptions()
yöntemini çağırı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 Yerler Veri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen fields
özelliğini AutocompleteOptions
özelliğine ekleyin veya setFields()
özelliğini mevcut bir Autocomplete
nesnesine çağırın.
autocomplete.setFields(["place_id", "geometry", "name"]);
Otomatik tamamlama için ön yargılar ve arama alanı sınırları tanımlayın
Aşağıdaki adımları uygulayarak otomatik tamamlama sonuçlarının yaklaşık konumunu veya alanını tercih edebilirsiniz:
Autocomplete
nesnesinin oluşturulmasıyla ilgili sınırları belirleyin.- Mevcut bir
Autocomplete
ile ilgili sınırları değiştirin. - Haritanın görüntü alanına olan sınırları ayarlayın.
- Aramayı sınırlarla sınırlandırın.
- Aramayı belirli bir ülkeyle sınırlar.
Önceki örnek, oluşturma sırasında ayar sınırlarını göstermektedir. 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
alanındaki arama alanını dikdörtgen sınırlarla değiştirmek için setBounds()
yöntemini ç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);
Haritanın görüntü alanına yönelik sınırları ayarlayın
Görüntü alanı değişse bile sonuçları haritanın görüntü alanına yönlendirmek için bindTo()
değerini kullanın.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Otomatik tamamlama tahminlerinin, haritanın görüntü alanındaki bağlantısını kaldırmak için unbind()
işlevini 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ı mevcut sınırlarıyla kısıtla
Sonuçları, harita görüntü alanı veya dikdörtgen sınırlara göre mevcut sınırlarla sınırlamak için strictBounds
seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle kısıtla
Otomatik tamamlama araması için en çok beş ülke içeren kümeyle sınırlı olmak üzere componentRestrictions
seçeneğini kullanın veya setComponentRestrictions()
yöntemini arayı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'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()
'ya iletilen değer için aşağıdakilerden birini belirleyebilirsiniz:
Tablo Türleri'nden Tablo 1'e 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 Türleri'nden Tablo 3'teki herhangi bir filtre. Tablo 3'ten yalnızca tek bir değer belirtebilirsiniz.
Aşağıdaki durumlarda istek reddedilir:
- Beşten fazla tür belirtirsiniz.
- Tanınmayan türleri belirtirsiniz.
- Tablo 1 veya Tablo 2'deki tüm türleri, Tablo 3'teki tüm filtrelerle birleştirebilirsiniz.
Otomatik Yer Tamamlama demosu, farklı yer türleri arasındaki tahmin farklarını gösterir.
Yer bilgilerini alma
Kullanıcı, otomatik tamamlama metin alanına ekli 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 veAutocomplete
nesnesineaddListener()
yöntemini kullanarak işleyiciyi ekleyin.- Seçilen nesne hakkında daha fazla bilgi edinmek için kullanabileceğiniz bir
PlaceResult
nesnesi almak içinAutocomplete
nesnesindeAutocomplete.getPlace()
yöntemini çağırın.
Varsayılan olarak, bir kullanıcı yer seçtiğinde otomatik tamamlama, seçili yer için mevcut tüm veri alanlarını döndürür ve siz de ilgili şekilde faturalandırılırsınız.
Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields()
kullanın. İstekte bulunabileceğiniz yer verisi alanlarının listesi dahil 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 belirtirken Autocomplete.setFields()
kullandığınızdan emin olun.
name
özelliği, Yerler Otomatik Tamamlama tahminlerindeki description
değerini içerir. Yerler Otomatik Tamamlama dokümanlarında description
hakkında daha fazla bilgi edinebilirsiniz.
Adres formları için adresin yapılandırılmış biçimde alınması yararlı olur. Seçili yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields()
numaralı telefonu arayıp address_components
alanını belirtin.
Aşağıdaki örnekte, adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmıştı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
Otomatik tamamlama hizmeti tarafından oluşturulan metin alanı varsayılan olarak 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 belirtiyorsanız uygulamanızda bu değerin yerelleştirilmesi gerekir. Google Haritalar JavaScript API'sinin kullanılacak dili nasıl seçtiği hakkında bilgi edinmek için lütfen yerelleştirme ile ilgili dokümanları okuyun.
Widget görünümünü özelleştirmek için Otomatik tamamlama ve SearchBox widget'larının stilini belirleme başlıklı makaleye bakın.
SearchBox widget'ı ekleme
SearchBox
, kullanıcıların "İstanbul'da pizza" veya "İstanbul'un yakınındaki ayakkabı mağazaları" gibi metin tabanlı bir coğrafi arama gerçekleştirmesine olanak tanır.
SearchBox
öğesini bir metin alanına ekleyebilirsiniz. Metin girildiğinde hizmet, açılır menü şeklinde tahminler döndürür.
SearchBox
, yerler (Yerler API'si tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'da pizza" kelime öbeğinin yanı sıra çeşitli pizzacıların adlarını içerebilir. 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
oluşturucu, 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çerebilenoptions
bağımsız değişkeni:bounds
, yer arama alanını belirten birgoogle.maps.LatLngBounds
nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere doğrudur, ancak bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları belirli bir coğrafi bölgedeki yerlere göre ağırlıklandırmak için boylam/boylam koordinatlarıyla belirtilir.
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
için arama alanını değiştirmek amacıyla SearchBox
nesnesinde setBounds()
yöntemini çağırın ve ilgili LatLngBounds
nesnesini geçirin.
Yer bilgilerini alma
Kullanıcı, arama kutusuna ekli tahminlerden bir öğe seçtiğinde hizmet places_changed
etkinliğini tetikler. Her biri PlaceResult
nesnesi olan birkaç tahmin içeren bir dizi almak için SearchBox
nesnesinde getPlaces()
çağırabilirsiniz.
PlaceResult
nesnesi hakkında daha fazla bilgi için
yer ayrıntıları 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 SearchBox widget'larının stilini belirleme başlıklı makaleye bakın.
Yer Otomatik Tamamlama Hizmeti tahminlerini programatik olarak alma
Tahminleri programatik olarak almak için
AutocompleteService
sınıfını kullanın. AutocompleteService
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ğinin ayrıntılarını içeren bir tahmin nesneleri dizisi döndürür.
Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete
ve SearchBox
tarafından sunulandan daha fazla kontrol istiyorsanız yararlıdır.
AutocompleteService
aşağıdaki yöntemleri gösterir:
getPlacePredictions()
, yer tahminlerini döndürür. Not: "Yer", Place API tarafından tanımlanan bir kuruluş, coğrafi konum veya önemli bir önemli nokta olabilir.getQueryPredictions()
, (Yerler API'sinin tanımladığı şekilde) yerleri ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'daki pizzacı" kelime öbeğini ve çeşitli pizzacıları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:
- Eşleşen tahmin
description
. distance_meters
, belirtilenAutocompletionRequest.origin
konumundan metre cinsinden mesafedir.matched_substrings
, açıklama bölümünde kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içerir. Bu, uygulamanızdaki bu alt dizeleri vurgulamak için yararlıdır. Çoğu durumda sorgu, açıklama alanının alt dizesi olarak görünür.length
, alt dizenin uzunluğudur.offset
, eşleşen alt dizenin gösterildiği açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.
place_id
, bir yeri benzersiz şekilde tanımlayan metinsel bir tanımlayıcıdır. Yer hakkında bilgi almak için bir Yer Ayrıntıları isteğininplaceId
alanına bu tanımlayıcıyı iletin. Yer kimliği kullanarak bir yere referans verme 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
, eşleşen alt dizenin gösterildiği açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.- Eşleşen terim
value
.
Aşağıdaki örnekte, "yakındaki pizzacı" ifadesi için bir sorgu tahmin isteği yürütülü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 tamamlamadaki arama 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çildiğinde sona erer. Her oturumda birden fazla sorgu ve ardından tek bir yer seçimi bulunabilir.
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ını kullanmanızı öneririz. sessionToken
parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum için herhangi bir oturum jetonu sağlanmamış gibi ücret alınır (her istek ayrı olarak faturalandırılır).
AutocompleteService.getPlacePredictions()
çağrısından kaynaklanan yerde tek bir Yer Ayrıntıları isteği yapmak için aynı oturum jetonunu kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve arama normal bir Yer Ayrıntıları 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. Birden fazla otomatik tamamlama oturumu için aynı jetonun kullanılması, bu otomatik tamamlama oturumlarını geçersiz kılar. 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şturup ardından bu jetonu bir AutocompleteService
içinde iletmeniz 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 SearchBox widget'larının stilini belirleme
Varsayılan olarak, Autocomplete
ve SearchBox
tarafından sağlanan kullanıcı arayüzü öğelerinin stili bir Google haritasına dahil edilecek şekilde belirlenir. Stili kendi sitenize uyacak şekilde ayarlayabilirsiniz. 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 |
Yer Otomatik 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 öğenin solunda gösterilen simge. |
pac-item |
Autocomplete veya SearchBox widget'ı tarafından sağlanan tahminler listesindeki bir öğe. |
pac-item:hover |
Kullanıcı fare imlecini üzerine getirdiğinde öğe. |
pac-item-selected |
Kullanıcı klavye ile seçtiğinde. Not: Seçili öğeler bu sınıfın ve pac-item sınıfının üyesi olacaktır.
|
pac-item-query |
Tahminin ana kısmı olan pac-item içindeki aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "New York'ta pizza" gibi metin tabanlı aramalar için sorgunun tam metnini içerir. Varsayılan olarak, pac-item-query siyah renkle gösterilir. pac-item öğesinde başka metin varsa bu metin pac-item-query dışında yer alır ve stilini pac-item ürününden devralır. Varsayılan olarak gridir. Ek metin genellikle bir adrestir. |
pac-matched |
Döndürülen tahminin, kullanıcının girişiyle eşleşen kısmı. Bu eşleşen metin, varsayılan olarak kalın metinle vurgulanır. Eşleşen metnin pac-item içindeki herhangi bir yerde olabileceğini unutmayın. Muhtemelen pac-item-query öğesinin bir parçası değildir ve hem pac-item-query içinde hem de pac-item içinde kalan metnin içinde olabilir. |
Yer Otomatik tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama özelliğinden 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ı iOS tamamlama widget'ı veya iOS için Yerler SDK'sını kullanmaktır Otomatik tamamlama kullanıcı arayüzü denetimi
- Temel Otomatik Yer Tamamlama veri alanları hakkında başından itibaren bilgi sahibi olun.
- Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilirler.
- API bir hata döndürürse uygulamanızın düzgün bir şekilde bozulduğundan emin olmak için hata işleme yöntemini kullanın.
- Seçim yapılmadığında uygulamanızın kullanıcılara uygun seçenekler sunduğundan emin olun.
Maliyet optimizasyonu ile ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetini kullanmanın maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek amacıyla Yer Ayrıntıları ve Otomatik Yer Tamamlama widget'larındaki alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına Fiyatlandırma özelliğine erişmek için Yer Otomatik Tamamlama özelliğinin programatik olarak uygulanmasını deneyin ve Yer Ayrıntıları yerine seçili yer hakkında Geocoding API sonuçları isteyin. Aşağıdaki koşulların her ikisi de sağlanıyorsa Geocoding API ile eşlenen İstek Başına Fiyatlandırma, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha maliyetlidir:
- Kullanıcının seçtiği yerin enlem/boylamı veya adresine ihtiyacınız varsa, Geokodlama API'si, bu bilgileri Yer Ayrıntıları çağrısından daha düşük bir fiyata gönderir.
- Kullanıcılar, ortalama dört veya daha az otomatik tamamlama tahmini isteği içinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun olabilir.
Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında herhangi bir bilgi gerektiriyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntılarıyla oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gerektirdiğinden, Yer Otomatik Tamamlama uygulamanızda oturum başına (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak) toplam 0,017 ABD doları maliyet ve geçerli Yer Veri SKU'ları bulunmalıdır (istediğiniz yer verisi alanlarına bağlı olarak}}
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahmindeki hem Yer Otomatik Tamamlama istekleri hem de Yer Ayrıntıları isteği dahildir. 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ı'nı isterken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtından yer kimliği
- Yer 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 gerekiyor
Coğrafi Kodlama API'sı, Yer Otomatik Tamamlama kullanımınızın performansına 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 yazdıklarına, kullanıldığı yere ve performans optimizasyonuyla ilgili en iyi uygulamaların uygulanıp uygulanmadığına bağlı olarak değişir.
Aşağıdaki soruyu yanıtlamak için, kullanıcının uygulamanızda otomatik yerleştirme tahmini seçmeden önce ortalama olarak kaç karakter girdiğini analiz edin.
Kullanıcılarınız otomatik olarak ortalama dört veya daha az istekte Yer Otomatik Tamamlama tahmini seçer mi?
Evet
Yer otomatik tamamlamayı, oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Geocoding API'yi çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresleri ve enlem/boylam koordinatlarını sunar. Dört Yer Otomatik Tamamlama - İstek Başına istek yapmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, dört yer isteğinin ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti, oturum başına 0,017 ABD doları olan oturum başına otomatik tamamlama fiyatından 0,01632 ABD doları olur.1
Kullanıcılarınızın aradıkları tahmini daha da az sayıda karakterle almasına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
Hayır
Yer Ayrıntılarıyla oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Bir kullanıcı otomatik yer tahmini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırma maliyetini aştığından Yer Otomatik Tamamlama kullanımınız, hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için toplam oturum başına 0,017 ABD doları şeklinde bir oturum jetonu kullanmalıdır. 1
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahmindeki hem Yer Otomatik Tamamlama istekleri hem de Yer Ayrıntıları isteği dahildir. Yalnızca Temel Veri alanları 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ı'nı isterken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtından yer kimliği
- Yer Otomatik Tamamlama isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veriler alanlarını belirten
fields
parametresi
Yer Otomatik Tamamlama isteklerini ertelemeyi göz önünde bulundurun
Kullanıcının otomatik olarak ilk üç veya dört karakter girene kadar Yer Otomatik Tamamlama isteğini geciktirme gibi stratejiler uygulayabilirsiniz. Böylece uygulamanız daha az istek gönderebilir. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteklerinde bulunursa, kullanıcı yedi karakter yazar ve bir Geocoding API isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * 0,00283 İstek Başına Otomatik Tamamlama + 0,005 Coğrafi Kodlama).1
Gecikme istekleri, ortalama programatik isteğinizi dört değerin altına düşebiliyorsa Geocoding API ile yüksek performanslı otomatik yer tamamlama uygulamasına yönelik yönergeleri uygulayabilirsiniz. Gecikme isteklerinin, her yeni tuş vuruşunda tahminleri görmeyi bekleyecek kullanıcılar tarafından gecikme olarak algılanabileceğini unutmayın.
Kullanıcılarınızın aradıkları tahmini daha az karakterden alması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ı'na bakın.
Performansla ilgili en iyi uygulamalar
Aşağıdaki yönergelerde, Yer Otomatik Tamamlama performansını optimize etmenin yolları açıklanmaktadır:
- Yer Otomatik Tamamlama uygulamanıza ülke kısıtlamaları, konuma ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini seçtikleri için widget'larla dil tercihi gerekmez.
- Yer otomatik tamamlama özelliğine bir harita eşlik ediyorsa harita görüntü alanına göre konuma ağırlık verebilirsiniz.
- Bir kullanıcının otomatik tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için daha alakalı sonuçlar elde etmek amacıyla 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 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 verme özelliğini kullanın.
- Çek Cumhuriyeti, Estonya ve Litvanya gibi alt tesis adresleri için Yer Otomatik Tamamlama desteğinin tamamlanmadığı ülkelerde alt tesis adresleri giren kullanıcılar. Örneğin, Çek adresi "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama özelliğinde kısmi bir tahmin sunar.
- Kullanıcılar, New York'ta "23-30 29th St, Queens" gibi yol segmenti ön eklerine veya Hawai'i, Kauai adasındaki "47-380 Kamehameha Hwy, Kaneohe" gibi adresler giren kullanıcılar.
Kullanım sınırları ve politikalar
Kotalar
Kota ve fiyatlandırma bilgileri için Yerler API'sinin Kullanım ve Faturalandırma belgelerine bakın.
Politikalar
Yerler Kitaplığı'nın kullanımı için Maps JavaScript API, Places API'si için açıklanan politikalara uygun olmalıdır.