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 İstemcisi'ne göz atın. Bu bağlantıdaki sayfada, Google Haritalar Hizmetleri için Java İstemcisi, Python İstemcisi ve Go İstemcisi de tanıtılmaktadır.
Giriş
Otomatik tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama
alanında arama türü davranışını vermek için otomatik tamamlama özelliğini kullanabilirsiniz.
Otomatik tamamlama hizmeti; tam kelimeler ve alt dizelerle eşleşerek yer adlarını, adresleri ve artı kodlarını çözebilir. Bu nedenle uygulamalar, anında yer tahminleri sağlamak için kullanıcı türü olarak sorgu gönderebilir.
Kullanmaya başlama
Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce, Yerler API'sinin Google Cloud Console'da etkinleştirilmiş olduğundan emin olun. Bu işlem, Maps JavaScript API için ayarladığınız projede gerçekleşir.
Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
Kontrol Paneli'ndeki API listesinde Places API'yi bulun.
API'yi listede görüyorsanız hazırsınız demektir. API listede yoksa etkinleştirin:
Kitaplık sekmesini görüntülemek için sayfanın üst kısmındaki API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak sol taraftaki menüden Kitaplık'ı seçin.
Places API'yi arayıp sonuçlar listesinden seçin.
ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Places API, Kontrol Paneli'nde API listesinde görünür.
Kitaplık yükleniyor
Rehber hizmeti, ana Maps JavaScript API kodundan ayrı, bağımsız bir kitaplıktır. Bu kitaplıkta bulunan işlevi kullanmak için önce Haritalar API'si önyükleme URL'sindeki libraries parametresini kullanarak işlevi yüklemeniz gerekir:
API, iki tür otomatik tamamlama widget'ı sunar. Bu widget'ları sırasıyla Autocomplete ve SearchBox sınıfları aracılığıyla ekleyebilirsiniz.
Ayrıca, otomatik tamamlama sonuçlarını programlı şekilde almak için AutocompleteService sınıfını da kullanabilirsiniz (Haritalar JavaScript API Referansı'na bakın: AutocompleteService class).
Autocomplete web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metni girdikçe otomatik tamamlama, yer tahminlerini bir açılır liste listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde bu yer hakkındaki bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz.
Şekil 1: Metin alanını otomatik tamamlama ve liste seçmeŞekil 2: Adres formunu doldurdu
SearchBox, web sayfanıza Autocomplete ile hemen hemen aynı bir metin giriş alanı ekler. Farklar aşağıda belirtilmiştir:
Aradaki temel fark, seçim listesinde gösterilen sonuçlardır. SearchBox, yerler (Yerler API'si tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'daki pizzacı" kelime öbeğini ve çeşitli pizzacıların adlarını içerebilir.
SearchBox, aramayı kısıtlamak için Autocomplete değerinden daha az seçenek sunar. Birincisinde, belirli bir LatLngBounds ile ilgili arama yapılmasına önyargılı olabilirsiniz. Sonuncusunda, sınırları belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve sınırlandırabilirsiniz. Daha fazla bilgi için aşağıya bakın.
Şekil 3: Arama Kutusu, arama terimleri ve yer tahminleri sunar.
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() yöntemini 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 bir dizi tahmin nesnesi döndürür. Her tahmin nesnesi, tahminin yanı sıra referans bilgileri ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.
Otomatik tamamlama widget'ı ekleme
Autocomplete widget'ı web sayfanızda bir metin giriş alanı oluşturur, bir kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminlerde bulunur ve bir getPlace() isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş, tek bir yere (Places API tarafından tanımlandığı şekilde) karşılık gelir.
Autocomplete oluşturucu, iki bağımsız değişken alır:
text türünde bir 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çtiği PlaceResult için Place Details yanıtına dahil edilecek bir fields veri dizisi. Özellik ayarlanmazsa veya ['ALL'] aktarılırsa kullanılabilir tüm alanlar döndürülür ve faturalandırılır (bu, üretim dağıtımları için önerilmez). Alanların listesi için PlaceResult adresini ziyaret edin.
Desteklenen türlerde listelendiği şekliyle, açık bir türü veya tür koleksiyonunu belirten types dizisi. Herhangi bir tür belirtilmezse tüm türler döndürülür.
bounds, içinde arama yapılacak alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere doğrudur, ancak bunlarla sınırlı değildir.
strictBounds, API'nin yalnızca 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 componentRestrictions kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu bir ülke kodu olarak geçirilmelidir. Ülke kodu listesi olarak birden fazla ülke belirtilmelidir.
Not: Bir ülke koduyla beklenmeyen sonuçlar alırsanız ülkeleri, bağımlı bölgeleri ve hedeflediğiniz coğrafi ilgi alanlarının yer aldığı bir kod kullandığınızdan emin olun. Kod bilgilerini Wikipedia: ISO 3166 ülke kodlarının listesi veya ISO Online Tarama Platformu'nda bulabilirsiniz.
placeIdOnly, Autocomplete widget'ına yalnızca Yer Kimliklerini alma talimatı vermek için kullanılabilir. Autocomplete nesnesinde getPlace() çağrılırken, kullanılabilir olan PlaceResult öğesine 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, otomatik yer doldurma işlevi tüm konum türlerini sunar, kullanıcının bulunduğu yerin yakınındaki tahminlere ağırlık verir ve kullanıcının seçtiği yer için mevcut tüm veri alanlarını getirir. Kullanım alanınıza göre daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.
Yapım aşamasındaki seçenekleri ayarlama
Autocomplete oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions parametresi kabul eder. Aşağıdaki örnekte, establishment türü yer isteğinde bulunmak için belirtilen bounds, componentRestrictions ve types seçenekleri belirlenerek belirtilen coğrafi bölgedekiler tercih ediliyor ve tahminler yalnızca ABD'deki yerlerle sınırlanıyor. fields seçeneğinin ayarlanması, kullanıcının seçtiği yer hakkında hangi bilgilerin döndürüleceğini belirtir.
Mevcut bir widget için bir seçeneğin değerini değiştirmek üzere setOptions() yöntemini çağırın.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
İhtiyacınız olmayan Yerler Veri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen fields özelliğini AutocompleteOptions özelliğine ekleyin veya setFields() özelliğini mevcut bir Autocomplete nesnesine çağırın.
Sonuçları, harita görüntü alanı veya dikdörtgen sınırlara göre mevcut sınırlarla sınırlamak için strictBounds seçeneğini ayarlayın.
autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle kısıtla
Otomatik tamamlama araması için en çok beş ülke içeren kümeyle sınırlı olmak üzere componentRestrictions seçeneğini kullanın veya setComponentRestrictions() yöntemini arayın.
Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() yöntemini çağırın. Bu kısıtlama, Yer Türleri'nde listelendiği gibi bir türü veya tür koleksiyonunu belirtir.
Herhangi bir kısıtlama belirtilmezse tüm türler döndürülür.
types seçeneğinin değeri veya setTypes()'ya iletilen değer için aşağıdakilerden birini belirleyebilirsiniz:
Kullanıcı, otomatik tamamlama metin alanına ekli tahminlerden bir yer seçtiğinde hizmet bir place_changed etkinliği tetikler. Yer ayrıntılarını almak için:
place_changed etkinliği için bir etkinlik işleyici oluşturun ve Autocomplete nesnesine addListener() yöntemini kullanarak işleyiciyi ekleyin.
Seçilen nesne hakkında daha fazla bilgi edinmek için kullanabileceğiniz bir PlaceResult nesnesi almak için Autocomplete nesnesinde Autocomplete.getPlace() yöntemini çağırın.
Varsayılan olarak, bir kullanıcı yer seçtiğinde otomatik tamamlama, seçili yer için mevcut tüm veri alanlarını döndürür ve siz de ilgili şekilde faturalandırılırsınız.
Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields() kullanın. İstekte bulunabileceğiniz yer verisi alanlarının listesi dahil PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak amacıyla, yalnızca kullanacağınız yer verilerini belirtirken Autocomplete.setFields()
kullandığınızdan emin olun.
name özelliği, Yerler Otomatik Tamamlama tahminlerindeki description değerini içerir. Yerler Otomatik Tamamlama dokümanlarındadescription hakkında daha fazla bilgi edinebilirsiniz.
Adres formları için adresin yapılandırılmış biçimde alınması yararlı olur. Seçili yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields() numaralı telefonu arayıp address_components alanını belirtin.
Aşağıdaki örnekte, adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmıştır.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
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;
Otomatik tamamlama hizmeti tarafından oluşturulan metin alanı varsayılan olarak standart yer tutucu metin içerir. Metni değiştirmek için input öğesinde placeholder özelliğini ayarlayın:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Not: Varsayılan yer tutucu metin otomatik olarak yerelleştirilir. Kendi yer tutucu değerinizi belirtiyorsanız uygulamanızda bu değerin yerelleştirilmesi gerekir. Google Haritalar JavaScript API'sinin kullanılacak dili nasıl seçtiği hakkında bilgi edinmek için lütfen
yerelleştirme ile ilgili dokümanları okuyun.
SearchBox, kullanıcıların "İstanbul'da pizza" veya "İstanbul'un yakınındaki ayakkabı mağazaları" gibi metin tabanlı bir coğrafi arama gerçekleştirmesine olanak tanır.
SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girildiğinde hizmet, açılır menü şeklinde tahminler döndürür.
SearchBox, yerler (Yerler API'si tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'da pizza" kelime öbeğinin yanı sıra çeşitli pizzacıların adlarını içerebilir. Kullanıcı listeden bir yer seçtiğinde, bu yer hakkındaki bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.
SearchBox oluşturucu, iki bağımsız değişken alır:
text türünde bir HTML input öğesi. Bu, SearchBox hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.
bounds özelliğini içerebilen options bağımsız değişkeni: bounds, yer arama alanını belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırlar içinde yer alan yerlere doğrudur, ancak bunlarla sınırlı değildir.
Aşağıdaki kod, sonuçları belirli bir coğrafi bölgedeki yerlere göre ağırlıklandırmak için boylam/boylam koordinatlarıyla belirtilir.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
SearchBox için arama alanını değiştirme
Mevcut bir SearchBox için arama alanını değiştirmek amacıyla SearchBox nesnesinde setBounds() yöntemini çağırın ve ilgili LatLngBounds nesnesini geçirin.
Kullanıcı, arama kutusuna ekli tahminlerden bir öğe seçtiğinde hizmet places_changed etkinliğini tetikler. Her biri PlaceResult nesnesi olan birkaç tahmin içeren bir dizi almak için SearchBox nesnesinde getPlaces() çağırabilirsiniz.
PlaceResult nesnesi hakkında daha fazla bilgi için
yer ayrıntıları sonuçları ile ilgili dokümanlara bakın.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// 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
kullanıcı arayüzü kontrolü eklemez. Bunun yerine her biri tahmin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğinin ayrıntılarını içeren bir tahmin nesneleri dizisi döndürür.
Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol istiyorsanız yararlıdır.
AutocompleteService aşağıdaki yöntemleri gösterir:
getPlacePredictions(), yer tahminlerini döndürür.
Not: "Yer", Place API tarafından tanımlanan bir kuruluş, coğrafi konum veya önemli bir önemli nokta olabilir.
getQueryPredictions(), (Yerler API'sinin tanımladığı şekilde) yerleri ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "yeni pizzacı" yazarsa seçim listesi, "İstanbul'daki pizzacı" kelime öbeğini ve çeşitli pizzacıların adlarını içerebilir.
Yukarıdaki yöntemlerin her ikisi de aşağıdaki biçimde bir tahmin nesneleri dizisi döndürür:
Eşleşen tahmin description.
distance_meters, belirtilen AutocompletionRequest.origin konumundan
metre cinsinden mesafedir.
matched_substrings, açıklama bölümünde kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içerir. Bu, uygulamanızdaki bu alt dizeleri vurgulamak için yararlıdır. Çoğu durumda sorgu, açıklama alanının alt dizesi olarak görünür.
length, alt dizenin uzunluğudur.
offset, eşleşen alt dizenin gösterildiği açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.
terms, sorgu öğelerini içeren bir dizidir. Bir yer için her öğe genellikle adresin bir bölümünü oluşturur.
offset, eşleşen alt dizenin gösterildiği açıklama dizesinin başlangıcından itibaren ölçülen karakter ofsetidir.
Eşleşen terim value.
Aşağıdaki örnekte, "yakındaki pizzacı" ifadesi için bir sorgu tahmin isteği yürütülür ve sonuç bir listede görüntülenir.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// 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 tamamlamadaki arama ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçildiğinde sona erer. Her oturumda birden fazla sorgu ve ardından tek bir yer seçimi bulunabilir.
Oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonlarını kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum için herhangi bir oturum jetonu sağlanmamış gibi ücret alınır (her istek ayrı olarak faturalandırılır).
AutocompleteService.getPlacePredictions() çağrısından kaynaklanan yerde tek bir Yer Ayrıntıları isteği yapmak için aynı oturum jetonunu kullanabilirsiniz.
Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve arama normal bir Yer Ayrıntıları isteği olarak ücretlendirilir. Otomatik tamamlama isteği için ücret alınmaz.
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Birden fazla otomatik tamamlama oturumu için aynı jetonun kullanılması, bu otomatik tamamlama oturumlarını geçersiz kılar. Geçersiz oturumlardaki tüm otomatik tamamlama istekleri, İstek başına otomatik tamamlama SKU'su kullanılarak tek tek ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.
Aşağıdaki örnekte, bir oturum jetonu oluşturup ardından bu jetonu bir AutocompleteService içinde iletmeniz gösterilmektedir (displaySuggestions() işlevi kısa olması için atlanmıştır):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonu birden fazla oturumda kullanmak, her isteğin ayrı ayrı faturalandırılmasına neden olur.
Otomatik tamamlama ve SearchBox widget'larının stilini belirleme
Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğelerinin stili bir Google haritasına dahil edilecek şekilde belirlenir. Stili kendi sitenize uyacak şekilde ayarlayabilirsiniz. Aşağıdaki CSS sınıfları kullanılabilir. Aşağıda listelenen tüm sınıflar hem Autocomplete hem de SearchBox widget'ları için geçerlidir.
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 listesindeki bir öğe.
pac-item:hover
Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected
Kullanıcı klavye ile seçtiğinde. Not: Seçili öğeler bu sınıfın ve pac-item sınıfının üyesi olacaktır.
pac-item-query
Tahminin ana kısmı olan pac-item içindeki aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "New York'ta pizza" gibi metin tabanlı aramalar için sorgunun tam metnini içerir. Varsayılan olarak, pac-item-query siyah renkle gösterilir. pac-item öğesinde başka metin varsa bu metin pac-item-query dışında yer alır ve stilini pac-item ürününden devralır. Varsayılan olarak gridir. Ek metin genellikle bir adrestir.
pac-matched
Döndürülen tahminin, kullanıcının girişiyle eşleşen kısmı. Bu eşleşen metin, varsayılan olarak kalın metinle vurgulanır. Eşleşen metnin pac-item içindeki herhangi bir yerde olabileceğini unutmayın. Muhtemelen pac-item-query öğesinin bir parçası değildir ve hem pac-item-query içinde hem de pac-item içinde kalan metnin içinde olabilir.
Yer Otomatik tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama özelliğinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Temel Otomatik Yer Tamamlama veri alanları hakkında başından itibaren bilgi sahibi olun.
Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilirler.
API bir hata döndürürse uygulamanızın düzgün bir şekilde bozulduğundan emin olmak için hata işleme yöntemini kullanın.
Seçim yapılmadığında uygulamanızın kullanıcılara uygun seçenekler sunduğundan emin olun.
Maliyet optimizasyonu ile ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetini kullanmanın maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek amacıyla Yer Ayrıntıları ve Otomatik Yer Tamamlama widget'larındaki alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına Fiyatlandırma özelliğine erişmek için Yer Otomatik Tamamlama özelliğinin programatik olarak uygulanmasını deneyin ve Yer Ayrıntıları yerine seçili yer hakkında Geocoding API sonuçları isteyin. Aşağıdaki koşulların her ikisi de sağlanıyorsa Geocoding API ile eşlenen İstek Başına Fiyatlandırma, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha maliyetlidir:
Kullanıcının seçtiği yerin enlem/boylamı veya adresine ihtiyacınız varsa, Geokodlama API'si, bu bilgileri Yer Ayrıntıları çağrısından daha düşük bir fiyata gönderir.
Kullanıcılar, ortalama dört veya daha az otomatik tamamlama tahmini isteği içinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun olabilir.
İhtiyaçlarınıza uygun Yer Otomatik 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.
Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında herhangi 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ı, konuma ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini seçtikleri için widget'larla dil tercihi gerekmez.
Yer otomatik tamamlama özelliğine bir harita eşlik ediyorsa harita görüntü alanına göre konuma ağırlık verebilirsiniz.
Bir kullanıcının otomatik tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için daha alakalı sonuçlar elde etmek amacıyla orijinal kullanıcı girişini yeniden kullanabilirsiniz:
Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API çağrısında orijinal kullanıcı girişini yeniden kullanın.
Kullanıcının ada veya adrese göre belirli bir yer için sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın.
Yalnızca belirli bir bölgede sonuçlar bekleniyorsa
konuma ağırlık verme özelliğini kullanın.
Geocoding API'yi kullanmanın en iyi olduğu diğer senaryolar şunlardır:
Çek Cumhuriyeti, Estonya ve Litvanya gibi alt tesis adresleri için Yer Otomatik Tamamlama desteğinin tamamlanmadığı ülkelerde alt tesis adresleri giren kullanıcılar. Örneğin, Çek adresi "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama özelliğinde kısmi bir tahmin sunar.
Kullanıcılar, New York'ta "23-30 29th St, Queens" gibi yol segmenti ön eklerine veya Hawai'i, Kauai adasındaki "47-380 Kamehameha Hwy, Kaneohe" gibi adresler giren kullanıcılar.
