Bu sayfada, Maps JavaScript API ile kullanılabilen istemci tarafı kitaplığı açıklanmaktadır. Sunucunuzdaki Yerler API'si web hizmetiyle çalışmak istiyorsanız Google Haritalar Hizmetleri için Node.js İstemcisine göz atın. Bu bağlantıdaki sayfada Google Haritalar Hizmetleri için Java İstemcisi, Python İstemcisi ve Go İstemcisi de tanıtılıyor.
Giriş
Otomatik tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanında türü önceden arama davranışı sağlamak 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ı çözümleyebilir. Bu nedenle uygulamalar, anında yer tahminleri sağlamak için kullanıcı türleri olarak sorgular gönderebilir.
Başlarken
Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce, ilk olarak Yerler API'sinin Google Cloud Console'da etkinleştirildiğinden emin olun. Bu işlem, Maps JavaScript API için yaptığınız projede yapılmalıdır.
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 her şey hazır demektir. API listelenmiyorsa etkinleştirin:
Kitaplık sekmesini görüntülemek için sayfanın üst kısmından API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
Places API ifadesini arayın, ardından sonuçlar listesinden seçin.
ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Places API görünür.
Kitaplık yükleniyor
Yerler hizmeti, ana Maps JavaScript API kodundan ayrı olan bağımsız bir kitaplıktır. Bu kitaplıkta bulunan işlevi kullanmak için öncelikle Haritalar API'si önyükleme URL'sindeki libraries parametresini kullanarak işlevi yüklemeniz gerekir:
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ı programatik olarak almak için AutocompleteService sınıfını kullanabilirsiniz (Haritalar JavaScript API Referansı'na bakın: AutocompleteService sınıfı).
Aşağıda mevcut sınıfların bir özetini bulabilirsiniz:
Autocomplete web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metin girdikçe otomatik tamamlama, açılır tahmin listesi biçiminde yer tahminlerini 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 olarak tamamlayın ve listeyi seçinŞekil 2: Doldurulan adres formu
SearchBox, web sayfanıza Autocomplete ile hemen hemen aynı bir metin giriş alanı ekler. Farklar şu şekildedir:
Aradaki temel fark, seçim listesinde görünen sonuçlardır. SearchBox, yerler (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" kelimesini girerse seçim listesi çeşitli pizza restoranlarının adlarının yanı sıra "İstanbul'da pizza" kelime öbeğini de içerebilir.
SearchBox, aramayı kısıtlamak için Autocomplete ile kıyaslandığında daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds açısından önyargılı yapabilirsiniz. Belirli bir ülke ve belirli yer türleriyle aramayı sınırlandırabilir ve sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıdaki bilgilere bakın.
Şekil 3: SearchBox, arama terimleri ve yer tahminleri sunar.
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() numaralı telefonu, eşleşen yerleri ve önerilen arama terimlerini almak için getQueryPredictions() numaralı telefonu arayın.
Not: AutocompleteService, kullanıcı arayüzü kontrolleri eklemez.
Bunun yerine, yukarıdaki yöntemler bir tahmin nesneleri dizisi döndürür. Her tahmin nesnesi, referans metni 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 yerlere dair tahminler sağlar ve bir getPlace() isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş, tek bir yere (Yerler API'sı 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 HTML input öğesi. Bu, otomatik tamamlama hizmetinin sonuçlarını izleyip ekleyacağı giriş alanıdır.
Aşağıdaki özellikleri içerebilen isteğe bağlı AutocompleteOptions bağımsız değişkeni:
Kullanıcı tarafından seçilen PlaceResult için Place Details yanıtına eklenecek bir veri dizisi fields. Bu özellik 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ü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, yer arama alanını belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere taraflıdır, ancak bunlarla sınırlı değildir.
strictBounds, API'nin yalnızca belirli bounds tarafından tanımlanan bölgede bulunan yerleri döndürmesi gerekip gerekmediğini belirten bir boolean'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 anda en fazla 5 ülkeye göre filtreleme yapmak için componentRestrictions özelliğini kullanabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu bir ülke kodu olarak geçirilmelidir. Ülke kodları listesi olarak birden fazla ülke geçirilmelidir.
Not: Ülke koduyla beklenmedik sonuçlar alırsanız istediğiniz ülkeleri, bağımlı bölgeleri ve coğrafi ilgi alanlarının özel bölgelerini içeren bir kod kullandığınızı doğrulayın. 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 nesnesinde getPlace() çağrılırken, kullanılabilir olan PlaceResult yalnızca place id, types ve name özellikleri ayarlanır. Döndürülen yer kimliğini Yerler, Coğrafi Kodlama, Yol Tarifi veya Mesafe Matrisi çağrılarıyla kullanabilirsiniz.
Otomatik tamamlama tahminlerini kısıtlama
Varsayılan olarak Yer Otomatik Tamamlama tüm yer türlerini sunar, kullanıcının konumuna yakın tahminlerde bulunur ve kullanıcının seçtiği yere ait tüm veri alanlarını getirir. Kullanım alanınıza bağlı olarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapıda seçenekleri ayarlama
Autocomplete oluşturucu, widget oluşturulurken kısıtlamalar belirlemek için bir AutocompleteOptions parametresi kabul eder. Aşağıdaki örnekte, establishment türü yer istemek için bounds, componentRestrictions ve types seçenekleri gösterilmektedir. Bu seçenekler, belirtilen coğrafi alandaki konumları destekler ve tahminleri yalnızca ABD içindeki yerlerle kısıtlar. fields seçeneğinin ayarlanması, kullanıcının seçilen yeriyle ilgili hangi bilgileri döndüreceğini belirtir.
Mevcut bir widget'ın 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,
types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
İ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 geçirilen AutocompleteOptions özelliğini AutocompleteOptions özelliğine dahil edin veya mevcut bir Autocomplete nesnesine setFields() işlevini çağırın.
Hem harita görüntü alanına hem de dikdörtgen sınırlara bağlı olarak, sonuçları geçerli sınırlarla sınırlamak üzere strictBounds seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle kısıtlama
Otomatik tamamlama aramasını en fazla beş ülkeyle kısıtlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() numaralı telefonu arayın.
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 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 aktarılan değer için aşağıdakilerden birini belirtebilirsiniz:
Bir kullanıcı otomatik tamamlama metin alanına ekli tahminlerden bir yer seçtiğinde hizmet place_changed etkinliği başlatır. Yer ayrıntılarını görmek için:
place_changed etkinliği için bir etkinlik işleyici oluşturun ve işleyiciyi eklemek için Autocomplete nesnesinde addListener() çağrısı yapın.
Seçilen nesne hakkında daha fazla bilgi edinmek için kullanabileceğiniz bir PlaceResult nesnesi almak için Autocomplete nesnesinde Autocomplete.getPlace() işlevini çağırın.
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 siz buna göre faturalandırılırsınız.
Hangi yer verisi alanlarının döndürüleceğini belirtmek için Autocomplete.setFields() özelliğini kullanın. Talep edebileceğ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 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ındadescription hakkında daha fazla bilgi edinebilirsiniz.
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() numaralı telefonu arayın ve address_components alanını belirtin.
Aşağıdaki örnekte adres formundaki alanları doldurmak için otomatik tamamlama kullanılı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();
}
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;
Varsayılan olarak, otomatik tamamlama hizmeti tarafından oluşturulan metin alanı 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 metin otomatik olarak yerelleştirilir. Kendi yer tutucu değerinizi belirtirseniz uygulamanızda bu değerin yerelleştirilmesi gerekir. Google Haritalar JavaScript API'sinin kullanılacak dili nasıl seçtiğiyle ilgili bilgi için lütfen yerelleştirme ile ilgili dokümanları okuyun.
SearchBox, kullanıcıların "İstanbul'da pizza" veya "İstanbul sokaklarında ayakkabı mağazaları" gibi metin tabanlı bir coğrafi arama yapmasına olanak tanır.
SearchBox metnini bir metin alanına ekleyebilirsiniz ve metin girildikçe hizmet, tahminleri bir açılır seçim listesi biçiminde döndürür.
SearchBox, yerler (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi "İstanbul, İ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 HTML input öğesi. Bu, SearchBox hizmetinin izlediği ve sonuçlarını eklediği giriş alanıdır.
bounds özelliğini içerebilen options bağımsız değişkeni: bounds, yer aranacak alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere göre taraflıdır ancak bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları tembellik/boylam koordinatları aracılığıyla belirtilen belirli bir coğrafi bölgedeki 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 için arama alanını değiştirmek isterseniz SearchBox nesnesinde setBounds() yöntemini çağırın ve ilgili LatLngBounds nesnesini geçirin.
Kullanıcı, arama kutusuna ekli tahminlerden bir öğe seçtiğinde hizmet places_changed etkinliği başlatır. Her biri PlaceResult nesnesi olan çeşitli tahminleri içeren bir diziyi almak için SearchBox nesnesinde getPlaces() işlevini çağırabilirsiniz.
PlaceResult nesnesi hakkında daha fazla bilgi için yer ayrıntıları sonuçları ile ilgili belgelere 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);
});
// 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);
});
Yer Otomatik 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 tahmin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir dizi tahmin nesnesi döndürür.
Bu özellik, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol sahibi olmak 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ımlandığı şekliyle bir kuruluş, coğrafi konum veya önemli nokta olabilir.
getQueryPredictions(), yerler (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesini döndürür. Örneğin, kullanıcı "yeni pizzacı" kelimesini girerse seçim listesi çeşitli pizza restoranlarının adlarının yanı sıra "İstanbul'da pizza" kelime öbeğini de 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, yerin AutocompletionRequest.origin cinsinden uzaklığını belirtir.
matched_substrings, açıklama bölümünde kullanıcının girişindeki öğelerle eşleşen bir alt dize kümesi 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öründüğü açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.
terms, sorgudaki öğeleri içeren bir dizidir. Bir yer için, her öğe genellikle adresin bir kısmını oluşturur.
offset, eşleşen alt dizenin göründüğü açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.
value eşleşen terim.
Aşağıdaki örnekte, "yakındaki pizzacılar" kelime öbeği için bir sorgu tahmin isteği yürütülmektedir 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;
// 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;
<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
with https://www.npmjs.com/package/@googlemaps/js-api-loader.
-->
<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 amaçları için otomatik tamamlama isteklerini gruplandırmak üzere oturum jetonları kullanır. Oturum jetonları, bir kullanıcının otomatik tamamlaması için 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çildiğinde sona erer. Her oturumda birden fazla sorgu ve bunu takip eden tek bir yer seçimi olabilir.
Oturum sona erdikten 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 oturum jetonunu yeniden kullanırsanız oturumdan 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ğinde bulunmak için aynı oturum jetonunu kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve arama, normal 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ı, otomatik tamamlama oturumlarını geçersiz kılar. Geçersiz oturumlardaki tüm otomatik tamamlama istekleri, İsteğe Göre 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 bir AutocompleteService içinde iletilmesi gösterilmektedir (displaySuggestions() işlevi kısa olması için çıkarılmış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ı jetonun birden fazla oturumda kullanılması, her isteğin ayrı ayrı faturalandırılmasına neden olur.
Otomatik Tamamlama ve Arama Kutusu widget'larını biçimlendirme
Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, bir Google haritasına eklenmek üzere biçimlendirilir. Stili kendi sitenize uyacak ş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.
Otomatik tamamlama ve SearchBox widget'ları için CSS sınıfları
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 listesinde bir öğe.
pac-item:hover
Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected
Kullanıcının klavye aracılığıyla seçtiği öğe. Not: Seçilen öğeler bu sınıfın ve pac-item sınıfının bir ü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. "İstanbul'da pizza" gibi metin tabanlı aramalar için sorgunun tam metnini içerir. Varsayılan olarak pac-item-query siyah renktedir. pac-item içinde 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 gri renk kullanılır. Ek metin genellikle bir adrestir.
pac-matched
Döndürülen tahminin, kullanıcının girişiyle eşleşen kısmıdır. Varsayılan olarak, eşleşen bu metin kalın metinle vurgulanır. Eşleşen metnin pac-item içinde herhangi bir yerde olabileceğini unutmayın. pac-item-query öğesinin bir parçası olması gerekmez ve bu kısmın bir kısmı pac-item-query içinde veya bir kısmı pac-item içinde kalan metin içinde olabilir.
Yer otomatik tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Temel Otomatik Tamamlama veri alanları'nı başından itibaren anlayın.
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 etkileyebilir.
API hata döndürürse uygulamanızın düzgün bir şekilde bozulmasını sağlamak için hata işleme yöntemini kullanın.
Uygulamanızın seçenek olmadığında işlendiğinden ve kullanıcılara devam etmek için bir yol sunduğundan emin olun.
Maliyet optimizasyonu en iyi uygulamaları
Temel maliyet optimizasyonu
Yer Otomatik 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ı düşünebilirsiniz. Ayrıca, Yer Ayrıntıları yerine seçilen yer hakkında Geocoded API sonuçları isteğinde bulunabilirsiniz. Aşağıdaki koşulların her ikisi de sağlanıyorsa istek başına fiyatlandırma, Geocode API ile eşlenmiş oturum başına fiyatlandırmaya (oturuma dayalı) fiyatlandırmadan daha maliyetlidir:
Kullanıcının seçtiği yerin enlem/boylamı veya adresine ihtiyacınız varsa Geo kodlama API'si, bu bilgileri Yer Ayrıntıları çağrısından daha düşük bir fiyatla sunar.
Kullanıcılar ortalama dört veya daha az otomatik tamamlama tahmin 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 Otomatik Yer Tamamlama uygulamasını seçme konusunda yardım almak için aşağıdaki soruya vereceğiniz yanıta karşılık gelen sekmeyi seçin.
Uygulamanız, seçilen tahminin adresi ve enlem/boylam bilgileri dışında bir bilgi gerektiriyor mu?
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ı, konum ön yargısı ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'larda dil tercihi gerekmez. Çünkü widget'lar, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini seçer.
Yer Otomatik Tamamlama'ya 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 almaya çalışmak için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocode 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 konum ağırlıklandırma kullanın.
Geocode API'yi kullanmanın en iyi olduğu diğer senaryolar:
Çek Cumhuriyeti, Estonya ve Litvanya gibi alt kuruluş adreslerini otomatik tamamlama özelliğinin eksik olduğu ülkelerde alt kuruluş adresleri giren kullanıcılar. Örneğin, Çek adresi "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
Kullanıcılar, New York City'de "23-30 29th St, Queens" gibi yol segmenti ön ekleri veya Hawai'i'deki Kauai adasında yer alan "47-380 Kamehameha Hwy, Kaneohe" gibi adresler giriyor.
