Yeni harita stilleri yakında Google Haritalar Platformu'nda kullanıma sunulacak. Harita stilinde yapılan bu güncelleme, yeni bir varsayılan renk paletinin yanı sıra harita deneyimleri ve kullanılabilirliğiyle ilgili iyileştirmeler içermektedir. Tüm harita stilleri Mart 2025'te otomatik olarak güncellenecektir. Bu özelliğin kullanılabilirliği ve bu özelliğe daha önce nasıl katılacağınız hakkında daha fazla bilgi edinmek 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ığı açıklanmaktadır. Sunucunuzda Places API web hizmetiyle çalışmak istiyorsanız Google Haritalar Hizmetleri için Node.js İstemcisi sayfasına 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ı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 yazma davranışını vermek için otomatik tamamlama özelliğini kullanabilirsiniz.
Otomatik tamamlama hizmeti; yer adlarını, adresleri ve artı kodlarını çözümleyerek tam kelimeler ve alt dizelerle eşleşebilir. Bu nedenle uygulamalar, kullanıcı yazarken yer hakkında tahminlerde bulunmak için sorgu gönderebilir.
Başlarken
Maps JavaScript API'de Yerler kitaplığını kullanmadan önce, ilk olarak Maps JavaScript API için ayarladığınız projede, Google Cloud Console'da Places API'nin etkinleştirildiğinden emin olun.
Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
Kontrol Paneli'ndeki API listesinde Places API'yi bulun.
API'yi listede görüyorsanız hazırsınız demektir. API listede yoksa etkinleştirin:
Kitaplık sekmesini görüntülemek için sayfanın üst kısmında API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
Places API'yi arayın ve ardından sonuçlar listesinden seçin.
ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Places API görünür.
Kitaplık yükleniyor
Yerler hizmeti, ana Maps JavaScript API kodundan ayrı olan bağımsız bir kitaplıktır. Bu kitaplıkta bulunan işlevi kullanmak için öncelikle Maps API önyükleme URL'sindeki libraries parametresini kullanarak işlevi yüklemeniz gerekir:
API, sırasıyla Autocomplete ve SearchBox sınıfları aracılığıyla ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar.
Ayrıca, otomatik tamamlama sonuçlarını programlı bir şekilde almak için AutocompleteService sınıfını kullanabilirsiniz (Haritalar JavaScript API Referansı: AutocompleteService sınıfı'na bakın).
Sunulan sınıfların özeti aşağıda verilmiştir:
Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişlerini izler. Kullanıcı metin girerken otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde, yerle ilgili bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz.
Şekil 1: Metin alanını otomatik tamamlama ve liste seçmeŞekil 2: Doldurulmuş adres formu
SearchBox, Autocomplete ile aynı şekilde bir metin giriş alanı ekler. Farklılıklar aşağıdaki gibidir:
Temel fark, seçim listesinde görünen sonuçlardadır. SearchBox, yerlerin (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" ifadesini ve çeşitli pizza restoranlarının adlarını içerebilir.
SearchBox, aramayı kısıtlamak için Autocomplete seçeneğinden daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds doğrulayacak şekilde ağırlıklandırabilirsiniz. İkinci kuralda, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve hem sınır belirleyebilirsiniz. Daha fazla bilgi için aşağıya bakın.
Şekil 3: Arama Kutusu, arama terimlerini ve yer tahminleri sunar.
Ayrıntıları aşağıda bulabilirsiniz.
Tahminleri programatik olarak almak için AutocompleteService nesnesi oluşturabilirsiniz. Eşleşen yerleri almak için getPlacePredictions() numaralı telefonu arayın veya eşleşen yerleri ve önerilen arama terimlerini almak için getQueryPredictions() numaralı telefonu arayın.
Not: AutocompleteService herhangi bir kullanıcı arayüzü kontrolü eklemez.
Bunun yerine, yukarıdaki yöntemler tahmin nesneleri dizisi döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgileri ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.
Otomatik Tamamlama widget'ı ekleme
Autocomplete widget'ı web sayfanızda bir metin giriş alanı oluşturur, bir kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminleri sağlar ve bir getPlace() isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş tek bir yere karşılık gelir (Places API tarafından tanımlandığı şekilde).
Autocomplete kurucusu iki bağımsız değişken alır:
text türünde bir HTML input öğesi. Bu, otomatik tamamlama hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.
Aşağıdaki özellikleri içerebilen isteğe bağlı AutocompleteOptions bağımsız değişkeni:
Kullanıcının seçilen PlaceResult için Place Details yanıtına dahil edilecek fields veri dizisi. Mülk ayarlanmazsa veya ['ALL'] geçirilirse mevcut tüm alanlar döndürülür ve faturalandırılır (bu, üretim dağıtımları için önerilmez). Alanların listesi için PlaceResult bölümüne bakın.
Desteklenen türlerde listelendiği şekliyle açık bir türü veya tür koleksiyonunu belirten bir types dizisi. Herhangi bir tür belirtilmezse tüm türler döndürülür.
bounds, yer aranacak alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere ağırlık verir ancak bunlarla sınırlı değildir.
strictBounds, API'nin yalnızca belirtilen bounds tarafından kesin olarak tanımlanan bölgeleri döndürmesinin gerekli olup olmadığını belirten bir boolean değeridir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışında sonuç döndürmez.
Sonuçları belirli gruplarla kısıtlamak için componentRestrictions kullanılabilir. Şu anda componentRestrictions kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak geçirilmelidir. Ülke kodu listesi olarak birden fazla ülke iletilmelidir.
placeIdOnly, Autocomplete widget'ına yalnızca Yer Kimliklerini alması talimatını vermek için kullanılabilir. Autocomplete nesnesinde getPlace() çağrılırken, kullanıma sunulan PlaceResult için 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
Otomatik Yer Tamamlama, varsayılan olarak kullanıcının konumuna yakın tahminler için eğilimli olarak tüm yer türlerini sunar ve kullanıcının seçtiği yer için kullanılabilir tüm veri alanlarını getirir. Kullanım alanınıza dayalı olarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapım aşamasında seçenekleri belirleyin
Autocomplete oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions parametresi kabul eder. Aşağıdaki örnekte bounds, componentRestrictions ve types seçenekleri, establishment türü yerler isteğinde bulunacak şekilde ayarlanarak belirtilen coğrafi bölgedeki konumları tercih edecek ve tahminleri yalnızca ABD'deki yerlerle sınırlandıracak. fields seçeneğinin ayarlanması, kullanıcının seçtiği yer hakkında hangi bilgilerin döndürüleceğini belirtir.
Mevcut bir widget'ta bir seçeneğin değerini değiştirmek için setOptions() numaralı telefonu arayın.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
İhtiyacınız olmayan Yer Verileri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya geçirilen AutocompleteOptions içine fields özelliğini ekleyin veya mevcut bir Autocomplete nesnesinde setFields() özelliğini çağırın.
Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre geçerli sınırlara göre kısıtlamak için strictBounds seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle sınırlama
Otomatik tamamlama aramasını en fazla beş ülkeden oluşan belirli bir grupla sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() çağırın.
Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() yöntemini çağırın. Bu kısıtlama, Yer Türleri bölümünde listelendiği gibi bir türü veya tür koleksiyonunu belirtir.
Herhangi bir kısıtlama belirtilmezse tüm türler döndürülür.
types seçeneğinin değeri veya setTypes() öğesine iletilen değer için şunlardan birini belirtebilirsiniz:
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() öğesini çağırın.
PlaceResult nesnesini almak için Autocomplete nesnesinde Autocomplete.getPlace() çağırın. Bu nesneyi daha sonra seçilen yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.
Varsayılan olarak bir kullanıcı bir yer seçtiğinde otomatik tamamlama, seçilen yer için mevcut tüm veri alanlarını döndürür ve uygun şekilde faturalandırılır.
Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields() değerini kullanın. İsteyebileceğiniz yer verisi alanlarının listesi de dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() kullandığınızdan emin olun.
name özelliği, Yerler Otomatik Tamamlama tahminlerindeki description öğesini içerir. description hakkında daha fazla bilgiyi Yerler Otomatik Tamamlama dokümanlarında bulabilirsiniz.
Adres formları için adresi yapılandırılmış biçimde almak yararlıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields() yöntemini çağırın ve address_components alanını belirtin.
Aşağıdaki örnekte, bir adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmaktadır.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
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 metin içerir. Metni değiştirmek için input öğesinde placeholder özelliğini ayarlayın:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Not: Varsayılan yer tutucu metin otomatik olarak yerelleştirilir. Kendi yer tutucu değerinizi belirtirseniz bu değerin yerelleştirilmesini uygulamanızda yapmanız gerekir. Google Maps JavaScript API'nin kullanılacak dili nasıl seçtiğiyle ilgili bilgi için lütfen
yerelleştirme ile ilgili dokümanları okuyun.
SearchBox, kullanıcıların "İstanbul'da pizza" veya "bostan yakınındaki ayakkabı mağazaları" gibi metne dayalı bir coğrafi arama gerçekleştirmelerine olanak tanır.
SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girildikçe hizmet, tahminleri açılır seçim listesi biçiminde döndürür.
SearchBox, yerlerin (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" kelime öbeğinin yanı sıra çeşitli pizza restoranlarının adlarını içerebilir. Bir kullanıcı listeden bir yer seçtiğinde, bu yer hakkındaki bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.
SearchBox kurucusu iki bağımsız değişken alır:
text türünde bir HTML input öğesi. Bu, SearchBox hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.
bounds özelliğini içerebilen bir options bağımsız değişkeni:
bounds, yerlerin aranacağı alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere ağırlık verir ancak bunlarla sınırlı değildir.
Aşağıdaki kodda, sonuçları enlem/boylam koordinatlarıyla belirtilen belirli bir coğrafi alandaki yerlere göre yönlendirmek için bounds parametresi kullanılır.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
Arama Kutusu için arama alanını değiştirme
Mevcut bir SearchBox için arama alanını değiştirmek üzere SearchBox nesnesinde setBounds() çağrısı yapın ve ilgili LatLngBounds nesnesini iletin.
Kullanıcı, arama kutusuna ekli tahminlerden bir öğe seçtiğinde hizmet bir places_changed etkinliği tetikler. Her biri PlaceResult nesnesi olan birkaç tahmin içeren bir dizi almak için SearchBox nesnesinde getPlaces() yöntemini çağırabilirsiniz.
PlaceResult nesnesi hakkında daha fazla bilgi için
yer ayrıntısı sonuçları ile ilgili dokümanlara bakın.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// 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 programlı olarak alma
Tahminleri programatik olarak almak için AutocompleteService sınıfını kullanın. AutocompleteService, herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, her biri tahmin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir dizi tahmin nesnesi döndürür.
Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla
denetime sahip olmak istiyorsanız yararlı olur.
AutocompleteService aşağıdaki yöntemleri sunar:
getPlacePredictions() yer tahminlerini döndürür.
Not: "Yer", Places API tarafından tanımlandığı şekilde bir tesis, coğrafi konum veya önemli bir önemli yer olabilir.
getQueryPredictions(), yerleri (Places API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "yeni pizza" yazarsa seçim listesi "New York, NY'de pizza" kelime öbeğinin yanı sıra çeşitli pizza restoranlarının adlarını içerebilir.
Yukarıdaki yöntemlerin her ikisi de aşağıdaki biçimde bir tahmin nesneleri dizisi döndürür:
description eşleşen tahmindir.
distance_meters, yerin belirtilen AutocompletionRequest.origin ile arasındaki mesafenin metre cinsinden değeridir.
matched_substrings, açıklamada, kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içerir. Bu, uygulamanızda bu alt dizeleri vurgulamak için faydalıdır. Çoğu durumda sorgu, açıklama alanının bir alt dizesi olarak görünür.
length, alt dizenin uzunluğudur.
offset, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
terms, sorgunun öğelerini içeren bir dizidir. Bir yer için her öğe genellikle adresin bir bölümünü oluşturur.
offset, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
value eşleşen terim.
Aşağıdaki örnekte, "yakında pizza" ifadesi için bir sorgu tahmini isteği yürütülmüştür ve sonuç bir listede görüntülenir.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// 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.
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(), otomatik tamamlama isteklerini faturalandırma amacıyla birlikte gruplandırmak için oturum jetonlarını (uygulandıysa) kullanabilir. Oturum jetonları, bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve kullanıcı bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu yapılabilir ve ardından tek bir yer seçimi yapılabilir.
Oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, hiçbir oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).
Aynı oturum jetonunu, AutocompleteService.getPlacePredictions() çağrısından kaynaklanan yer hakkında tek bir Yer Ayrıntıları isteği yapmak için kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve arama, normal Yer Ayrıntısı isteği olarak ücretlendirilir. Otomatik tamamlama isteği için ücret alınmaz.
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonu birden fazla Otomatik Tamamlama oturumunda kullanmak, bu Otomatik Tamamlama oturumlarını geçersiz kılar ve geçersiz oturumlardaki tüm Otomatik Tamamlama istekleri, İstek Başına Otomatik Tamamlama SKU'su kullanılarak ayrı ayrı ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.
Aşağıdaki örnekte, oturum jetonu oluşturulup ardından AutocompleteService içinde gösterilmektedir (displaySuggestions() işlevi kısa olması için atlanmıştır):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonu birden fazla oturumda kullanmak, her isteğin ayrı ayrı faturalandırılmasına neden olur.
Otomatik Tamamlama ve Arama Kutusu widget'larının stil özelliklerini ayarlama
Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, bir Google haritasına eklenmek üzere tasarlanmıştır. Stili kendi sitenize uyacak şekilde ayarlamak isteyebilirsiniz. Aşağıdaki CSS sınıfları kullanılabilir. Aşağıda listelenen tüm sınıflar, hem Autocomplete hem de SearchBox widget'ları için geçerlidir.
Otomatik Tamamlama ve SearchBox 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 açılır liste olarak görünür.
pac-icon
Tahmin listesindeki her bir öğenin solunda gösterilen simge.
pac-item
Autocomplete veya SearchBox widget'ı tarafından sağlanan tahmin listesindeki bir öğe.
pac-item:hover
Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected
Kullanıcı klavye aracılığıyla seçtiğinde öğe. Not: Seçilen öğeler, bu sınıfın ve pac-item sınıfının üyesi olacak.
pac-item-query
Tahminin ana parçası olan pac-item içindeki bir aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "İstanbul'da pizza" gibi metin tabanlı aramalarda, sorgunun tam metnini içerir. Varsayılan olarak pac-item-query siyah renklidir. pac-item içinde ek metin varsa pac-item-query alanının dışındadır ve stilini pac-item öğesinden devralır. Varsayılan olarak gri renktedir. Ek metin genellikle bir adrestir.
pac-matched
Döndürülen tahminin, kullanıcı girişiyle eşleşen kısmı. Varsayılan olarak, bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin pac-item içinde herhangi bir yerde olabileceğini unutmayın. Bu, pac-item-query kapsamında olmayabilir ve kısmen pac-item-query içinde ve kısmen pac-item içindeki kalan metinde olabilir.
Yer Seçici bileşenini kullanma
Not: Bu örnekte açık kaynak kitaplık kullanılmaktadır. Kitaplıkla ilgili destek ve geri bildirim için BENİOKU sayfasına göz atın.
Web bileşenlerini deneyin. Son kullanıcıların otomatik tamamlamayı kullanarak belirli bir adresi veya yeri aramasına olanak tanıyan metin girişini etkinleştirmek için
Yer Seçici web bileşenini kullanın.
Şekil 1: Otomatik tamamlama özelliğini kullanarak belirli bir adresi veya yeri aramak için metin girişi
Otomatik Yer Tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Otomatik Yer Tamamlama özelliğinin temel veri alanlarını daha en baştan anlayın.
Konuma ağırlık verme ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkisi olabilir.
API bir hata döndürürse uygulamanızın sorunsuz bir şekilde bozulmasını sağlamak için hata işlemeyi kullanın.
Uygulamanızın hiçbir seçim olmadığında bunu karşıladığından ve kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.
Maliyet optimizasyonuyla ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetinin kullanım maliyetini optimize etmek için, yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larında alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına fiyatlandırmaya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Geocoding API sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığı takdirde, Coğrafi Kodlama API'si ile eşlenen İstek Başına fiyatlandırma, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntıları çağrısından daha azı için sunar.
Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
İhtiyaçlarınıza uygun Otomatik Yer Tamamlama uygulamasını seçme konusunda yardım için aşağıdaki soruya verdiğiniz yanıta uygun sekmeyi seçin.
Başvurunuz, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerektiriyor mu?
Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansını optimize etme yöntemleri açıklanmaktadır:
Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, yere ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtiği için dil tercihi gerekli değildir.
Otomatik Yer Tamamlama'ya bir harita eşlik ediyorsa, konumu harita görünümüne göre yönlendirebilirsiniz.
Kullanıcının Otomatik tamamlama tahminlerinden birini seçmediği durumlarda (genellikle bu tahminlerin hiçbiri istenen sonuç adresi olmadığından), daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API'ye yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
Kullanıcının ada veya adrese göre belirli bir yer için sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın.
Yalnızca belirli bir bölgede sonuçlar bekleniyorsa konuma ağırlık vermeyi kullanın.
Geocoding API'yi kullanmanın en iyi olduğu diğer senaryolar:
Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin tamamlanmadığı ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresi giren kullanıcılar. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
