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'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ı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ı sağlamak için otomatik tamamlama özelliğini kullanabilirsiniz.
Otomatik tamamlama hizmeti; yer adları, adresler ve artı kodları çözümlenerek tam kelimeler ve alt dizelerle eşleşebilir. Böylece uygulamalar, anında yer tahminleri sağlamak için kullanıcı yazarken sorgu gönderebilir.
Kullanmaya başlama
Maps JavaScript API'de Yerler kitaplığını kullanmadan önce, ilk olarak Maps JavaScript API için oluşturduğunuz projede, Google Cloud Console'da Places API'nin etkinleştirildiğinden emin olun.
Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
Kontrol Paneli'ndeki API listesinde Places API'yi arayın.
Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
Places API'yi arayın ve sonuçlar listesinden seçin.
ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Places API görünür.
Kitaplık yükleniyor
Yerler hizmeti, ana Maps JavaScript API kodundan ayrı olan bağımsız bir kitaplıktır. Bu kitaplıkta yer alan işlevi kullanmak için önce Maps API önyükleme URL'sindeki libraries parametresini kullanarak bu işlevi yüklemeniz gerekir:
API, sırasıyla Autocomplete ve SearchBox sınıfları aracılığıyla ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar.
Ayrıca, otomatik tamamlama sonuçlarını programlı bir şekilde almak için AutocompleteService sınıfını kullanabilirsiniz (Haritalar JavaScript API Referansı: AutocompleteService sınıfı'na bakın).
Sunulan sınıfların özeti aşağıda verilmiştir:
Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metin girdiğinde otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde, bu yerle ilgili bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz.
Şekil 1: Metin alanını ve seçim listesini otomatik doldurmaŞekil 2: Doldurulmuş adres formu
SearchBox, Autocomplete ile hemen hemen aynı şekilde bir metin giriş alanı ekler. Farklar aşağıda belirtilmiştir:
Başlıca fark, seçim listesinde gösterilen sonuçlardadır. SearchBox, yerleri (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizza şubelerinin adları yer alabilir.
SearchBox, aramayı kısıtlamak için Autocomplete seçeneğinden daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds değerine göre yönlendirebilirsiniz. İkinci seçenekte, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıdaki bilgilere göz atın.
Şekil 3: Arama Kutusu arama terimleri ve yer tahminleri sunar.Aşağıda ayrıntıları inceleyin.
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ü denetimi eklemez.
Bunun yerine, yukarıdaki yöntemler bir dizi tahmin nesneleri döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgileri ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.
Otomatik Tamamlama widget'ı ekleme
Autocomplete widget'ı web sayfanızda bir metin giriş alanı oluşturur, kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminleri sağlar ve getPlace() isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her bir giriş tek bir yere karşılık gelir (Places API tarafından tanımlandığı şekilde).
Autocomplete kurucusu iki bağımsız değişken alır:
text türünde bir 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ı bir 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. Özellik ayarlanmazsa veya ['ALL'] aktarılırsa kullanılabilir tüm alanlar döndürülür ve ücretlendirilir (bu, üretim dağıtımları için önerilmez). Alanların listesi için PlaceResult bölümünü inceleyin.
Desteklenen türlerde listelendiği gibi açık bir türü veya tür koleksiyonunu belirten bir types dizisi. Tür belirtilmezse tüm türler döndürülür.
bounds, yerlerin aranacağı alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere
yönlüdür, ancak bunlarla sınırlı değildir.
strictBounds, API'nin yalnızca belirtilen bounds ile tanımlanan bölgede bulunan yerleri döndürmesi gerekip gerekmediğini belirten bir boolean öğesidir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışındaki sonuçları döndürmez.
componentRestrictions, sonuçları belirli gruplarla kısıtlamak için kullanılabilir. Şu anda componentRestrictions kullanarak en fazla 5 ülkeye göre filtreleyebilirsiniz. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Ülke kodlarının bir listesi olarak birden çok ülke iletilmelidir.
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 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 hizmetlerine yapılan çağrılarda kullanabilirsiniz.
Otomatik Tamamlama tahminlerini kısıtlama
Varsayılan olarak Yer Otomatik Tamamlama, kullanıcının bulunduğu konumun yakınındaki tahminler için eğilimli olacak şekilde tüm yer türlerini sunar ve kullanıcının seçtiği yer için mevcut tüm veri alanlarını getirir. Kullanım alanınıza dayalı olarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapım aşamasında seçenekleri belirleyin
Autocomplete oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions parametresini kabul eder. Aşağıdaki örnekte, establishment türü yerler istemek için bounds, componentRestrictions ve types seçenekleri belirtilmektedir. Bu seçenekler, belirtilen coğrafi bölgedeki yerler için tercih edilir ve tahminleri yalnızca ABD içindeki yerlerle sınırlandırılır. fields seçeneğinin ayarlanması, kullanıcının seçilen yerle ilgili hangi bilgilerin döndürüleceğini belirtir.
Mevcut bir widget'ta bir seçeneğin değerini değiştirmek için setOptions() numaralı telefonu arayın.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
İhtiyacınız olmayan Yer Verileri SKU'ları için faturalandırılmamak üzere veri alanları belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions öğesine fields özelliğini ekleyin veya mevcut bir Autocomplete nesnesinde setFields() yöntemini çağırın.
Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre geçerli sınırlara göre kısıtlamak için strictBounds seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle sınırlama
Otomatik tamamlama aramasını beş taneye kadar ülke içeren belirli bir grupla sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() numaralı telefonu çağırın.
Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() yöntemini çağırın. Bu kısıtlama, Yer Türleri bölümünde listelendiği gibi bir tür veya tür koleksiyonu belirtir.
Herhangi bir kısıtlama belirtilmezse tüm türler döndürülür.
types seçeneğinin değeri veya setTypes() öğesine iletilen değer için aşağıdakilerden birini belirtebilirsiniz:
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() değerini çağırın.
Autocomplete nesnesinde Autocomplete.getPlace() yöntemini çağırarak PlaceResult nesnesini alın. Daha sonra bu nesneyi seçilen yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.
Varsayılan olarak bir kullanıcı bir yer seçtiğinde otomatik tamamlama, seçilen yer için mevcut tüm veri alanlarını döndürür ve buna göre faturalandırılırsınız.
Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields() değerini kullanın. İsteyebileceğiniz yer verisi alanlarının listesi de dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() kullandığınızdan emin olun.
name özelliği, Yerler Otomatik Tamamlama tahminlerinden gelen description bilgisini içerir. description hakkında daha fazla bilgiyi Yerler Otomatik Tamamlama dokümanlarında bulabilirsiniz.
Adres formları için adresi yapılandırılmış biçimde almak faydalıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields() değerini çağırın ve address_components alanını belirtin.
Aşağıdaki örnekte, bir adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmaktadır.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
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ği hakkında bilgi için lütfen
yerelleştirme ile ilgili dokümanları okuyun.
SearchBox, kullanıcıların "İstanbul'da pizza" veya "İzmir Caddesi'ndeki ayakkabı mağazaları" gibi metne dayalı bir coğrafi arama gerçekleştirmesine olanak tanır.
SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girildikçe hizmet, tahminleri açılır seçim listesi biçiminde döndürür.
SearchBox, yerleri (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizzacıların adları yer alabilir. Bir kullanıcı listeden bir yer seçtiğinde, bu yer hakkındaki bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.
SearchBox kurucusu iki bağımsız değişken alır:
text türünde bir 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 google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere dayalı olup bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları enlem/boylam koordinatlarıyla belirtilen belirli bir coğrafi alandaki yerlere göre ağırlıklandırmak için bounds parametresini kullanır.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
SearchBox için arama alanını değiştirme
Mevcut bir SearchBox öğesinin arama alanını değiştirmek için SearchBox nesnesinde setBounds() çağrısı yapın ve ilgili LatLngBounds nesnesini iletin.
Kullanıcı, arama kutusuna eklenen tahminlerden bir öğe seçtiğinde hizmet bir places_changed etkinliği tetikler. Her biri PlaceResult nesnesi olan çeşitli tahminler içeren bir dizi almak için SearchBox nesnesinde getPlaces() çağırabilirsiniz.
PlaceResult nesnesi hakkında daha fazla bilgi için
yer ayrıntısı sonuçları hakkındaki dokümanlara bakın.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// 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);
});
Otomatik Yer Tamamlama Hizmeti tahminlerini programatik olarak alma
Tahminleri programatik olarak almak için AutocompleteService sınıfını kullanın. AutocompleteService, herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, her biri tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir tahmin nesneleri dizisi döndürür.
Kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol sahibi olmak istiyorsanız bu yöntem yararlıdır.
AutocompleteService aşağıdaki yöntemleri sunar:
getPlacePredictions() yer tahminlerini döndürür.
Not: "Yer", Places API tarafından tanımlandığı şekliyle bir işletme, coğrafi konum veya önemli bir yer olabilir.
getQueryPredictions(), yerleri (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "pizza in new" yazarsa seçim listesinde "pizza in New York, NY" ifadesi ve çeşitli pizza restoranlarının adları yer alabilir.
Yukarıdaki yöntemlerin her ikisi de aşağıdaki biçimde bir tahmin nesneleri dizisi döndürür:
description, eşleşen tahmindir.
distance_meters, yerin 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, bu alt dizeleri uygulamanızda vurgulamak için kullanışlıdır. Sorgu, çoğu durumda açıklama alanının bir alt dizesi olarak görünür.
length, alt dizenin uzunluğudur.
offset, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
terms, sorgu öğelerini içeren bir dizidir. Bir yer için her öğe genellikle adresin bir bölümünü oluşturur.
offset, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
value eşleşen terim.
Aşağıdaki örnekte, "pizza yakınındaki" kelime öbeği için bir sorgu tahmini isteği yürütülmüştür ve sonuç bir listede görüntülenir.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// 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(), faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonları kullanır. Oturum jetonları, kullanıcının otomatik tamamlama özelliğinin sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir.
Bir oturum sonlandırıldıktan sonra jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).
AutocompleteService.getPlacePredictions() öğesine yapılan bir çağrıdan kaynaklanan yer hakkında tek bir Yer Ayrıntıları isteği göndermek için aynı oturum jetonunu kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntısı isteğiyle birleştirilir ve arama, normal Yer Ayrıntısı isteği olarak ücretlendirilir. Otomatik tamamlama isteği için ücret alınmaz.
Her yeni oturum için benzersiz bir oturum jetonu aktardığınızdan emin olun. Aynı jetonu birden fazla Otomatik Tamamlama oturumu için kullanmak, bu Otomatik Tamamlama oturumlarını geçersiz kılar ve geçersiz oturumlardaki tüm Otomatik Tamamlama istekleri, İstek Başına Otomatik Tamamlama SKU'su kullanılarak tek tek ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.
Aşağıdaki örnekte, bir oturum jetonu oluşturulup daha sonra AutocompleteService içinde iletilmesi gösterilmektedir (displaySuggestions() işlevi kısa olması için atlanmıştır):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
Her yeni oturum için benzersiz bir oturum jetonu aktardığınızdan emin olun. Aynı jetonu birden fazla oturumda kullanmak, her isteğin ayrı ayrı faturalandırılmasına neden olur.
Otomatik Tamamlama ve Arama Kutusu widget'larının stil özelliklerini ayarlama
Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, Google haritasına eklenmek üzere tasarlanmıştır. Stili kendi sitenize uygun şekilde ayarlayabilirsiniz. Aşağıdaki CSS sınıfları mevcuttur. Aşağıda listelenen tüm sınıflar, hem Autocomplete hem de SearchBox widget'ları için geçerlidir.
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 bir açılır liste olarak görünür.
pac-icon
Tahmin listesindeki her bir öğenin solunda gösterilen simge.
pac-item
Autocomplete veya SearchBox widget'ı tarafından sağlanan tahmin listesindeki bir öğe.
pac-item:hover
Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected
Kullanıcı klavyeyle seçtiğinde öğe. Not: Seçilen öğeler bu sınıfın ve pac-item sınıfının üyesi olacak.
pac-item-query
Tahminin ana parçası olan pac-item içindeki bir aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "İstanbul'da pizza" gibi metin tabanlı aramalarda, sorgunun tam metnini içerir. pac-item-query varsayılan olarak siyah renklidir. pac-item içinde ek metin varsa pac-item-query alanının dışındadır ve stilini pac-item öğesinden devralır. Varsayılan olarak gri renklidir. Ek metin genellikle bir adrestir.
pac-matched
Döndürülen tahminin kullanıcı girişiyle eşleşen bölümü. Varsayılan olarak, bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin, pac-item sınırları içinde herhangi bir yerde olabileceğini unutmayın. Bu ülke mutlaka pac-item-query kapsamında olmayabilir ve hem pac-item-query içinde hem de kısmen pac-item içinde kalan metnin içinde olabilir.
Otomatik Yer Tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Otomatik Yer Tamamlama veri alanlarıyla ilgili temel bilgileri en baştan geliştirin.
Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlı olsa da otomatik tamamlama performansı üzerinde önemli etkileri olabilir.
API hata döndürürse uygulamanızın sorunsuz bir şekilde eskimesini sağlamak için hata işlemeyi kullanın.
Uygulamanızın seçim olmadığında işlemleri karşıladığından ve kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.
Maliyet optimizasyonuyla ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetini kullanma maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larında alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına fiyatlandırma'ya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'sı sonuçlarını istemek için Yer Otomatik Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen İstek Başına fiyatlandırması, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir tutar için sağlar.
Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
İ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 karşılık gelen sekmeyi seçin.
Başvurunuzda, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerekiyor 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ı, konuma ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtiğinden, dil tercihi gerekli değildir.
Otomatik Yer Tamamlama'yı bir harita içeriyorsa, konumu harita görüntü alanına göre taşıyabilirsiniz.
Kullanıcının Otomatik Tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığından, daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API çağrısında orijinal kullanıcı girişini yeniden kullanın.
Kullanıcının belirli bir yer için ad veya adrese göre sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın.
Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
Coğrafi Kodlama API'sini kullanmayı en iyi açıklayan diğer senaryolar:
Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresleri giren kullanıcılar. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Yer Tamamlama'da kısmi bir tahmin sağlar.
