Duyuru: Yakında Google Haritalar Platformu'nda yeni temel harita stili kullanıma sunulacak. Harita stilinde yapılan bu güncelleme; yeni bir varsayılan renk paleti, modernleştirilmiş raptiyeler, harita deneyimleri ve kullanılabilirlik ile ilgili iyileştirmeler içerir. Tüm harita stilleri Mart 2025'te otomatik olarak güncellenecektir. Kullanılabilirlik ve özelliği daha erken etkinleştirme hakkında daha fazla bilgi için Google Haritalar Platformu için yeni harita stili başlıklı makaleyi inceleyin.
Bu sayfada, Maps JavaScript API ile kullanılabilen istemci tarafı kitaplık açıklanmaktadır. Sunucunuzda Places API web hizmetiyle çalışmak istiyorsanız Google Haritalar Hizmetleri için Node.js İstemcisi'ne göz atın. Bu bağlantıdaki sayfada, Google Haritalar Hizmetleri için Java İstemcisi, Python İstemcisi ve Go İstemcisi de tanıtılmaktadır.
Giriş
Otomatik tamamlama, Maps JavaScript API'deki Yerler Kitaplığı'nın bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının önceden yazmayla arama davranışını kazandırmak için otomatik tamamlamayı kullanabilirsiniz.
Otomatik tamamlama hizmeti, tam kelimeler ve alt dizelerle eşleşerek yer adlarını, adresleri ve Plus Code'ları çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken sorgu göndererek anında yer tahminleri sağlayabilir. Places API tarafından tanımlandığı üzere, "yer" bir kuruluş, coğrafi konum veya önemli bir yer olabilir.
Başlarken
Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce, Google Cloud Konsolu'nda, Maps JavaScript API için oluşturduğunuz projede Yerler API'sinin etkinleştirildiğinden emin olun.
Proje seç düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
Kontrol panelindeki API listesinde Places API'yi bulun.
API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
Sayfanın üst kısmında API'yi etkinleştir'i seçerek Kitaplık sekmesini görüntüleyin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
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ığı yükleme
Yerler hizmeti, ana Maps JavaScript API kodundan ayrı, kendi kendine yeten bir kitaplıktır. Bu kitaplıktaki işlevleri kullanmak için öncelikle Haritalar API önyükleme URL'sindeki libraries parametresini kullanarak kitaplığı yüklemeniz gerekir:
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ı programatik olarak almak için AutocompleteService sınıfını kullanabilirsiniz (bkz. Maps JavaScript API Referansı: AutocompleteService sınıfı).
Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanda 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.
Şekil 1: Otomatik tamamlama metin alanı ve seçim listesiŞekil 2: Doldurulmuş adres formu
SearchBox, Autocomplete ile hemen hemen aynı şekilde web sayfanıza bir metin giriş alanı ekler. Farklar şunlardır:
Ana fark, seçim listesinde görünen sonuçlardadır. SearchBox, yerler (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir.
SearchBox, aramayı kısıtlamak için Autocomplete'e kıyasla daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds'ye yönlendirebilirsiniz. İkincisinde, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir, ayrıca sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıya bakın.
Şekil 3: Arama kutusu, arama terimlerini ve yer tahminlerini gösterir.
Ayrıntıları aşağıda bulabilirsiniz.
Tahminleri programatik olarak almak için bir AutocompleteService nesnesi oluşturabilirsiniz. Eşleşen yerleri almak için getPlacePredictions()'ü, eşleşen yerlerin yanı sıra önerilen arama terimlerini almak için getQueryPredictions()'ü çağırın.
Not: AutocompleteService, kullanıcı arayüzü denetimleri eklemez.
Bunun yerine, yukarıdaki yöntemler bir tahmin nesnesi dizisi döndürür. Her tahmin nesnesi, tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğiyle ilgili 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 listesinde yer alan yerlerle ilgili tahminler sağlar ve getPlace() isteğiyle yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş tek bir yere (Yerler API'si tarafından tanımlandığı şekilde) karşılık gelir.
Autocomplete kurucusu iki bağımsız değişken alır:
text türündeki bir HTML input öğesi. Bu, otomatik tamamlama hizmetinin izleyeceği ve sonuçlarını 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çin Place Details yanıtına eklenecek bir veri dizisi fields. Mülk ayarlanmazsa veya ['ALL'] iletilirse 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çin PlaceResult başlıklı makaleyi inceleyin.
Desteklenen türler bölümünde listelenen 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 bir google.maps.LatLngBounds nesnesi. Sonuçlar bu sınırlar içinde bulunan yerlere yöneliktir ancak bunlarla sınırlı değildir.
strictBounds, API'nin yalnızca belirli bounds tarafından tanımlanan bölgedeki yerleri döndürmesi gerekip gerekmediğini belirten bir boolean bağımsız değişkenidir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışındaki sonuçları döndürmez.
componentRestrictions, sonuçları belirli gruplarla sınırlamak için kullanılabilir. Şu anda componentRestrictions'yi kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Birden fazla ülke, ülke kodları listesi olarak iletilmelidir.
Not: Bir ülke koduyla beklenmedik sonuçlar alırsanız hedeflediğiniz ülkeleri, bağlı bölgeleri ve coğrafi açıdan ilgi çekici özel alanları içeren bir kod kullandığınızdan emin olun. Kod bilgilerini Wikipedia: ISO 3166 ülke kodları listesi veya ISO Online Tarama Platformu'nda bulabilirsiniz.
placeIdOnly, Autocomplete widget'ına yalnızca yer kimliklerini döndürmesini bildirmek için kullanılabilir. Autocomplete nesnesi üzerinde getPlace() çağrıldığında, kullanıma sunulan PlaceResult'de yalnızca place id, types ve name ö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.
Otomatik tamamlama tahminlerini kısıtlama
Varsayılan olarak Yer Otomatik Tamamlama, kullanıcının konumuna yakın tahminlere göre ağırlıklandırılmış 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 göre daha alakalı tahminler sunmak için yer otomatik tamamlama seçeneklerini ayarlayın.
İnşaat aşamasında seçenekleri ayarlama
Autocomplete kurucusu, widget oluşturulurken kısıtlamalar belirlemek için bir AutocompleteOptions parametresi kabul eder. Aşağıdaki örnekte, bounds, componentRestrictions ve types seçenekleri establishment türündeki yerleri isteyecek şekilde ayarlanmıştır. Bu örnekte, belirtilen coğrafi alandaki yerler tercih edilir ve tahminler yalnızca ABD'deki yerlerle sınırlandırılır. fields seçeneğini ayarlamak, kullanıcının seçtiği yerle ilgili hangi bilgilerin döndürüleceğini belirtir.
Mevcut bir widget için bir seçeneğin değerini değiştirmek üzere setOptions() işlevini çağırın.
TypeScript
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
İhtiyacınız olmayan Places Veri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions öğesine fields özelliğini ekleyin veya mevcut bir Autocomplete nesnesinde setFields()'yi çağırın.
Sonuçları haritanın görüntü alanına göre yönlendirmek için bindTo() değerini kullanın. Bu görüntü alanı değişse bile sonuçlar haritanın görüntü alanına göre yönlendirilir.
Sonuçları harita görüntü alanına veya dikdörtgen sınırlara göre mevcut sınırlarla kısıtlamak için strictBounds seçeneğini ayarlayın.
autocomplete.setOptions({strictBounds:true});
Tahminleri belirli bir ülkeyle kısıtlama
Otomatik tamamlama aramasını en fazla beş ülke içeren belirli bir ülke grubuyla sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() işlevini çağırın.
Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() işlevini çağırın. Bu kısıtlama, Yer Türleri bölümünde listelenen bir türü veya tür koleksiyonunu belirtir.
Kısıtlama belirtilmezse tüm türler döndürülür.
types seçeneğinin değeri veya setTypes()'a iletilen değer için aşağıdakilerden birini belirtebilirsiniz:
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 üzere Autocomplete nesnesinde addListener() işlevini çağırın.
Autocomplete nesnesinde Autocomplete.getPlace() çağrısı yaparak PlaceResult nesnesini alın. Bu nesneyi, seçili yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.
Varsayılan olarak, 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 size buna göre faturalandırılırsınız.
Hangi yer veri alanlarının döndürüleceğini belirtmek için Autocomplete.setFields() türünü kullanın. İsteyebilirsiniz yer verisi alanlarının listesi dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmaktan kaçınmak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() kullandığınızdan emin olun.
name mülkü, Yerler otomatik tamamlama tahminlerinden gelen description değerini içerir. description hakkında daha fazla bilgiyi Yerler Otomatik Tamamlama dokümanlarında bulabilirsiniz.
Adres formlarında, 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() işlevini çağırın ve address_components alanını belirtin.
Aşağıdaki örnekte, adres formunda alanları doldurmak için otomatik tamamlama özelliği kullanılmaktadır.
TypeScript
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=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")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).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();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=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;
Otomatik tamamlama hizmeti tarafından oluşturulan metin alanı varsayılan olarak standart yer tutucu metni 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 metni 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 edinmek için lütfen
yerelleştirme ile ilgili dokümanları okuyun.
SearchBox, kullanıcıların "New York'ta pizza" veya "robson street yakınındaki ayakkabı mağazaları" gibi metne dayalı coğrafi aramalar yapmasına olanak tanır.
SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girilirken hizmet, açılır seçim listesi biçiminde tahminler döndürür.
SearchBox, yerler (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir. Kullanıcı listeden bir yer seçtiğinde, söz konusu yerle ilgili 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ündeki bir HTML input öğesi. Bu, SearchBox hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.
bounds mülkünü içerebilen bir options bağımsız değişkeni:
bounds, yerlerin aranacağı alanı belirten bir google.maps.LatLngBounds
nesnesi. Sonuçlar bu sınırlar dahilindeki yerlere yöneliktir ancak bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları enlem/boylam koordinatları aracılığıyla belirtilen belirli bir coğrafi bölgedeki yerlere yönlendirmek için bounds parametresini kullanır.
Mevcut bir SearchBox nesnesinin arama alanını değiştirmek için SearchBox nesnesinde setBounds() işlevini çağırın ve ilgili LatLngBounds nesnesini iletin.
Kullanıcı arama kutusuna eklenmiş 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() işlevini çağırabilirsiniz.
PlaceResult nesnesi hakkında daha fazla bilgi için
yer ayrıntısı sonuçları ile ilgili dokümanları inceleyin.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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);});
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 tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğiyle ilgili ayrıntıları içeren bir tahmin nesnesi dizisi döndürür.
Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol sahibi olmak istiyorsanız faydalıdır.
AutocompleteService aşağıdaki yöntemleri gösterir:
getPlacePredictions(), yer tahminlerini döndürür.
Not: "Yer", Places API tarafından tanımlandığı üzere bir kuruluş, coğrafi konum veya önemli bir yer olabilir.
getQueryPredictions(), konumları (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir.
Yukarıdaki yöntemlerin ikisi de aşağıdaki biçimde bir tahmin nesnesi dizisi döndürür:
description, eşleşen tahmindir.
distance_meters, belirtilen AutocompletionRequest.origin'a olan mesafeyi (metre cinsinden) gösterir.
matched_substrings, açıklamada kullanıcının girişindeki öğelerle eşleşen bir dizi alt dize içerir. Bu, uygulamanızdaki bu alt dizelerin vurgulanması 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öründüğü açıklama dizenin başlangıcından itibaren ölçülen karakter ofsetidir.
place_id, bir yeri benzersiz şekilde tanımlayan metin tabanlı bir tanımlayıcıdır. Yerle ilgili bilgileri almak için bu tanımlayıcıyı Yer Ayrıntıları isteğininplaceId alanına gönderin. Yer kimliğiyle bir yere referans verme 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, eşleşen alt dizenin göründüğü açıklama dizenin başlangıcından itibaren ölçülen karakter ofsetidir.
value, eşleşen terimdir.
Aşağıdaki örnekte, "yakınımda pizza" ifadesi için bir sorgu tahmini isteği yürütülür ve sonuç bir listede gösterilir.
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">functioninitService():void{constdisplaySuggestions=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)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// 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">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<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>
AutocompleteService.getPlacePredictions(), faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonlarını (uygulanmışsa) kullanabilir. Oturum jetonları, kullanıcının 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 bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir.
Bir oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonlarını kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).
AutocompleteService.getPlacePredictions() çağrısından elde edilen yerde 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ıları isteğiyle birleştirilir ve çağrı 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 gönderdiğinizden emin olun. Aynı jetonun birden fazla Otomatik Tamamlama oturumunda kullanılması, 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, bir oturum jetonunun oluşturulması ve ardından bir AutocompleteService içinde iletilmesi gösterilmektedir (displaySuggestions() işlevi kısalık için atlanmıştır):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
Her yeni oturum için benzersiz bir oturum jetonu gönderdiğinizden emin olun. Aynı jetonun birden fazla oturumda kullanılması, her isteğinin ayrı ayrı faturalandırılmasına neden olur.
Otomatik Tamamlama ve Arama Kutusu widget'larına stil uygulama
Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri bir Google haritasına eklenecek şekilde biçimlendirilir. 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.
Otomatik Tamamlama ve Arama Kutusu widget'ları için CSS sınıfları
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
Tahminler listesinde her öğenin solunda gösterilen simge.
pac-item
Autocomplete veya SearchBox widget'ı tarafından sağlanan tahminler listesinde bir öğe.
pac-item:hover
Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected
Kullanıcının klavyeyle seçtiği öğe. Not: Seçilen öğeler bu sınıfın ve pac-item sınıfının üyesi olur.
pac-item-query
Tahminin ana kısmı olan pac-item içindeki bir span. Coğrafi konumlar için bu alan, "Sydney" 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. pac-item-query varsayılan olarak siyah renkle gösterilir. pac-item içinde ek metin varsa bu metin pac-item-query dışındadır ve stilini pac-item'ten devralır. Varsayılan olarak gri renklidir. Ek metin genellikle bir adrestir.
pac-matched
Döndürülen tahminin, kullanıcının 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 metin, pac-item-query'ün bir parçası olmayabilir ve kısmen pac-item-query'te, kısmen de pac-item'teki kalan metinde bulunabilir.
Yer Adı Otomatik Tamamlama optimizasyonu
Bu bölümde, yer otomatik tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Yer Otomatik Tamamlama'nın temel veri alanlarını baştan itibaren öğrenin.
Konum önyargısı ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
API hata döndürdüğünde uygulamanızın sorunsuz bir şekilde bozulmasını sağlamak için hata işleme özelliğini kullanın.
Uygulamanızın, seçim yapılmadığında kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.
Maliyet optimizasyonuyla ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Yer Otomatik Tamamlama hizmetinin 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 Yer Otomatik Tamamlama widget'larındaki 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 Coğrafi Kodlama API sonuçlarını istemek için Otomatik Yer Tamamlama'nın programatik olarak uygulanmasını değerlendirin. Geocoding API ile birlikte kullanılan istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılanıyorsa oturum başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
Yalnızca kullanıcının seçtiği yerin enlem/boylamına veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri bir Yer Ayrıntıları çağrısından daha kısa sürede sağlar.
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 maliyetli olabilir.
İhtiyaçlarınıza uygun yer otomatik tamamlama uygulamasını seçmenize yardımcı olması için aşağıdaki soruya verdiğiniz yanıta karşılık gelen sekmeyi seçin.
Uygulamanız, seçilen tahminin adresi ve enlem/boylam dışında başka bilgi gerektiriyor mu?
Aşağıdaki kurallarda, yer otomatik tamamlama performansını optimize etme yöntemleri açıklanmaktadır:
Yer Otomatik Tamamlama uygulamanıza ülke kısıtlamaları, konum önyargısı ve (programlı 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 gerekmez.
Yer Otomatik Tamamlama özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre kaydırabilirsiniz.
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ıdan 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 yerle ilgili ad veya adresle sorgu girmesini bekliyorsanız Yer Bul isteği kullanın.
Sonuçların yalnızca belirli bir bölgede elde edilmesi bekleniyorsa konumlu önyargı kullanın.
Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
Bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adresleri giren kullanıcılar Örneğin, Çek adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
New York City'de "23-30 29th St, Queens" veya Hawai'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleriyle adres giren kullanıcılar.
