Place Autocomplete

Giriş

Otomatik tamamlama, Maps JavaScript API'deki Yerler kitaplığının bir özelliğidir. Otomatik tamamlama özelliğini kullanarak uygulamalarınıza Google Haritalar arama alanının yazarken arama yapma davranışını kazandırabilirsiniz. Otomatik tamamlama hizmeti, tam kelimeler ve alt dizelerle eşleşebilir, yer adlarını, adresleri ve Plus Code'ları çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken anında yer tahminleri sağlamak için sorgu gönderebilir. Places API'de tanımlandığı şekliyle "yer"; bir kuruluş, coğrafi konum veya önemli bir ilgi alanı olabilir.

Başlarken

Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce Google Cloud Console'da, Maps JavaScript API için ayarladığınız projede Yerler API'nin etkinleştirildiğini doğrulayın.

Etkinleştirilen API'lerinizin listesini görüntülemek için:

1. Google Cloud Console'a gidin.
2. Proje seç düğmesini tıklayın, ardından Maps JavaScript API için ayarladığınız projeyi seçip Aç'ı tıklayın.
3. Kontrol panelindeki API listesinde Places API'yi bulun.
4. Listede API'yi görüyorsanız hazırsınız demektir. Ancak bu proje eski durumdadır. Eski aşama ve eski hizmetlerden daha yeni hizmetlere geçiş hakkında daha fazla bilgi için Eski ürünler ve özellikler başlıklı makaleyi inceleyin. Places API (Yeni) üzerinde henüz GA ürünü olarak kullanılamayan Autocomplete ve SearchBox widget'ları için istisna uygulanır.

Kitaplığı yükleme

Yer hizmeti, ana Maps JavaScript API kodundan ayrı, bağımsız bir kitaplıktır. Bu kitaplıkta yer alan özellikleri kullanmak için öncelikle kitaplığı Maps API bootstrap URL'sindeki libraries parametresini kullanarak yüklemeniz gerekir:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Daha fazla bilgi için Kitaplıklara Genel Bakış başlıklı makaleyi inceleyin.

Sınıfların özeti

API, sırasıyla Autocomplete ve SearchBox sınıflarını kullanarak ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar. Ayrıca, otomatik tamamlama sonuçlarını programatik olarak almak için AutocompleteService sınıfını kullanabilirsiniz (bkz. Maps JavaScript API Referansı: AutocompleteService sınıfı).

Mevcut sınıfların özeti aşağıda verilmiştir:

• Autocomplete web sayfanıza bir metin girişi alanı ekler ve bu alana girilen karakterleri izler. Kullanıcı metin girerken otomatik tamamlama, açılır liste şeklinde yer tahminleri 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.

  

  

• SearchBox, Autocomplete ile benzer şekilde web sayfanıza bir metin giriş alanı ekler. Farklar şunlardır:
  • Aradaki temel fark, seçim listesinde gösterilen sonuçlardır. SearchBox, yerleri (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizzalar" yazdığında seçim listesinde "New York, NY'taki pizzalar" ifadesinin yanı sıra çeşitli pizza restoranlarının adları da yer alabilir.
  • SearchBox, aramayı kısıtlama konusunda Autocomplete'e kıyasla daha az seçenek sunar. İlkinde, aramayı belirli bir LatLngBounds'ya yönlendirebilirsiniz. İkinci durumda, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir, ayrıca sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıya bakın.

  

  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(), eşleşen yerleri ve önerilen arama terimlerini almak için getQueryPredictions() öğesini çağırın. Not: AutocompleteService herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, yukarıdaki yöntemler bir tahmin nesneleri dizisi döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgilerini 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şi alanı oluşturur, kullanıcı arayüzü seçim listesinde yer tahminleri sağlar ve 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şturucusu iki bağımsız değişken alır:

• text türünde bir HTML input öğesi. Bu, otomatik tamamlama hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.
• Aşağıdaki özellikleri içerebilen isteğe bağlı bir AutocompleteOptions bağımsız değişkeni:
  • Kullanıcının seçtiği PlaceResult için Place Details yanıtına eklenecek bir veri dizisi fields. Özellik ayarlanmazsa veya ['ALL'] iletilirse 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 başlıklı makaleyi inceleyin.
  • Desteklenen türler bölümünde listelendiği gibi, açık bir türü veya tür koleksiyonunu belirten bir types dizisi. Tür belirtilmezse tüm türler döndürülür.
  • bounds, yer aramak için kullanılacak alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar bu sınırlar içinde yer alan yerlere yönelik olarak taraflıdır ancak bu yerlerle sınırlı değildir.
  • strictBounds, API'nin yalnızca belirtilen bounds ile tanımlanan bölgenin kesin sınırları içinde kalan yerleri döndürmesi gerekip gerekmediğini belirten bir boolean. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışındaki sonuçları döndürmez.
  • componentRestrictions, sonuçları belirli gruplarla sınırlamak için kullanılabilir. En fazla 5 ülkeye göre filtre uygulamak için componentRestrictions kullanabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Birden fazla ülke, ülke kodlarının listesi olarak iletilmelidir.

    Not: Bir ülke koduyla beklenmedik sonuçlar alırsanız amaçladığınız ülkeleri, bağımlı bölgeleri ve coğrafi ilgi alanlarını içeren bir kod kullandığınızı doğrulayın. Kod bilgilerini Wikipedia: List of ISO 3166 country codes (Wikipedia: ISO 3166 ülke kodları listesi) veya ISO Online Browsing Platform'da (ISO Online Göz Atma Platformu) bulabilirsiniz.

  • placeIdOnly, Autocomplete widget'ına yalnızca yer kimliklerini alması talimatını vermek için kullanılabilir. getPlace(), Autocomplete nesnesinde çağrıldığında, PlaceResult yalnızca place id, types ve name özellikleri ayarlanmış olarak kullanılabilir. Döndürülen yer kimliğini Places, Geocoding, Directions veya Distance Matrix hizmetlerine yapılan çağrılarda kullanabilirsiniz.

Otomatik tamamlama tahminlerini kısıtlama

Yer Otomatik Tamamlama, varsayılan olarak kullanıcının konumuna yakın tahminler için önyargılı bir ş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 göre daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.

İnşaat sırasında seçenekleri ayarlama

Autocomplete oluşturucu, widget oluşturulurken kısıtlamaları ayarlamak için AutocompleteOptions parametresini kabul eder. Aşağıdaki örnekte, bounds, componentRestrictions ve types seçenekleri, establishment türü yerler istenmesi, belirtilen coğrafi alan içindeki yerlerin tercih edilmesi ve tahminlerin yalnızca ABD'deki yerlerle sınırlandırılması için ayarlanır. fields seçeneği ayarlandığında, kullanıcının seçtiği yer hakkında hangi bilgilerin döndürüleceği belirtilir.

Mevcut bir widget'ın seçenek değerini değiştirmek için setOptions() işlevini çağırın.

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);
index.ts

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");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

Veri alanlarını belirtme

İhtiyacınız olmayan Places Data SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions öğelerine fields özelliğini ekleyin veya mevcut bir Autocomplete nesnesinde setFields() işlevini çağırın.

autocomplete.setFields(["place_id", "geometry", "name"]);

Otomatik tamamlama için önyargıları ve arama alanı sınırlarını tanımlama

Otomatik tamamlama sonuçlarını, yaklaşık bir konumu veya alanı tercih edecek şekilde aşağıdaki yöntemlerle yönlendirebilirsiniz:

• Autocomplete nesnesinin oluşturulmasıyla ilgili sınırları ayarlayın.
• Mevcut bir Autocomplete öğesinin sınırlarını değiştirme.
• Sınırları haritanın görüntü alanına ayarlayın.
• Aramayı sınırlar içinde tutun.
• Aramayı belirli bir ülkeyle sınırlayın.

Önceki örnekte, oluşturma sırasında sınırların nasıl ayarlanacağı gösterilmektedir. Aşağıdaki örneklerde diğer önyargı teknikleri gösterilmektedir.

Mevcut bir otomatik tamamlama özelliğinin sınırlarını değiştirme

Mevcut bir setBounds() üzerindeki arama alanını dikdörtgen sınırlara değiştirmek için Autocomplete işlevini çağırın.

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.ts

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.js

Sınırları haritanın görüntü alanına ayarlayın

Sonuçları, görüntü alanı değişse bile haritanın görüntü alanına göre yönlendirmek için bindTo() kullanın.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Otomatik tamamlama tahminlerinin haritanın görünüm alanıyla bağlantısını kaldırmak için unbind() simgesini kullanın.

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.ts

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Örneği görüntüleyin

Aramayı mevcut sınırlara göre kısıtlama

Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre mevcut sınırlar ile 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() numaralı telefonu arayın.

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

Örneği görüntüleyin

Yer türlerini kısıtlama

Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() numaralı telefonu arayın. Bu kısıtlama, Yer Türleri'nde listelendiği gibi bir türü veya tür koleksiyonunu belirtir. Kısıtlama belirtilmezse tüm türler döndürülür.

types seçeneğinin değeri veya setTypes()'ye aktarılan değer için şunlardan birini belirtebilirsiniz:

• Yer Türleri'ndeki Tablo 1 veya Tablo 2'den en fazla beş değer içeren bir dizi. Örneğin:

  types: ['hospital', 'pharmacy', 'bakery', 'country']

  veya:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• Yer Türleri'nden Tablo 3'teki filtrelerden herhangi biri. Yalnızca Tablo 3'teki tek bir değeri belirtebilirsiniz.

İstek şu durumlarda reddedilir:

• Beşten fazla tür belirtirseniz.
• Tanınmayan türleri belirtirsiniz.
• Tablo 1 veya Tablo 2'deki türleri Tablo 3'teki filtrelerle karıştırırsanız.

Places Autocomplete demosu, farklı yer türleri arasındaki tahmin farklılıklarını gösterir.

Demoyu ziyaret edin

Yer bilgisi alma

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:

1. place_changed etkinliği için bir etkinlik işleyici oluşturun ve işleyiciyi eklemek üzere Autocomplete nesnesinde addListener() işlevini çağırın.
2. Seçilen yer hakkında daha fazla bilgi almak için kullanabileceğiniz bir PlaceResult nesnesi almak üzere Autocomplete nesnesinde Autocomplete.getPlace() işlevini çağırın.

Varsayılan olarak, bir kullanıcı bir yer seçtiğinde otomatik tamamlama, seçilen yerle ilgili tüm kullanılabilir veri alanlarını döndürür ve buna göre faturalandırılırsınız. Hangi yer verisi alanlarının döndürüleceğini belirtmek için Autocomplete.setFields() türünü kullanın. İsteyebileceğiniz yer verileri 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 üzere, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() simgesini kullandığınızdan emin olun.

name özelliği, Yer Otomatik Tamamlama tahminlerinden gelen description değerini içerir. description hakkında daha fazla bilgiyi Yerler Otomatik Tamamlama dokümanlarında bulabilirsiniz.

Adres formlarında, adresi yapılandırılmış biçimde almak faydalıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields()'ı ç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.

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();
}
index.ts

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;
index.js

Örneği görüntüleyin

Yer tutucu metni özelleştirme

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 edinmek için yerelleştirme ile ilgili dokümanları okuyun.

Widget'ın görünümünü özelleştirmek için Autocomplete ve SearchBox widget'larının stilini belirleme başlıklı makaleyi inceleyin.

Arama kutusu widget'ı ekleme

SearchBox, kullanıcıların "New York'ta pizza" veya "Robson Caddesi yakınındaki ayakkabı mağazaları" gibi metin tabanlı coğrafi aramalar yapmasına olanak tanır. SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girildikçe hizmet, açılır seçim listesi şeklinde tahminler döndürür.

SearchBox, yerleri (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni pizza" ifadesini girerse seçim listesinde "New York, NY'ta pizza" ifadesinin yanı sıra çeşitli pizza satış noktalarının adları da yer alabilir. Kullanıcı listeden bir yer seçtiğinde bu yerle ilgili bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.

SearchBox oluşturucusu iki bağımsız değişken alır:

• text türünde bir HTML input öğesi. Bu, SearchBox hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.
• options bağımsız değişkeni, bounds özelliğini içerebilir: bounds, yer aramak için alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar bu sınırlar içinde yer alan yerlere yönelik önyargılıdır ancak bu yerlerle sınırlı değildir.

Aşağıdaki kod, sonuçları enlem/boylam koordinatları kullanılarak belirtilen belirli bir coğrafi bölgedeki yerlere doğru yönlendirmek için sınır 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'ın arama alanını değiştirme

Mevcut bir SearchBox için arama alanını değiştirmek üzere SearchBox nesnesinde setBounds() işlevini çağırın ve ilgili LatLngBounds nesnesini iletin.

Örneği görüntüleyin

Yer bilgisi alma

Kullanıcı, arama kutusuna eklenen tahminlerden birini seçtiğinde hizmet bir places_changed etkinliği tetikler. Her biri bir PlaceResult nesnesi olan birkaç tahmin içeren bir dizi almak için SearchBox nesnesinde getPlaces() işlevini çağırabilirsiniz.

PlaceResult nesnesi hakkında daha fazla bilgi için yer ayrıntısı sonuçları ile ilgili dokümanlara bakın.

// 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);
});
index.ts

// 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);
});
index.js

Örneği görüntüleyin

Widget'ın görünümünü özelleştirmek için Autocomplete ve SearchBox widget'larının stilini belirleme başlıklı makaleyi inceleyin.

Yer Otomatik Tamamlama Hizmeti tahminlerini programatik olarak alma

Tahminleri programlı 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. Bu, yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulan kullanıcı arayüzü üzerinde daha fazla kontrol sahibi olmak istediğiniz durumlarda faydalıdır.

AutocompleteService aşağıdaki yöntemleri kullanıma sunar:

• getPlacePredictions() yer tahminleri döndürür. Not: Places API'de tanımlandığı şekilde "yer" bir kuruluş, coğrafi konum veya önemli bir ilgi çekici nokta olabilir.
• getQueryPredictions(), yerleri (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "yeni pizza" yazdığında seçim listesinde "New York, NY'ta pizza" ifadesinin yanı sıra çeşitli pizza restoranlarının adları da yer alabilir.

Yukarıdaki yöntemlerin her ikisi de aşağıdaki biçimde bir tahmin nesneleri dizisi döndürür:

• Eşleşen tahmin: description
• distance_meters, yerin belirtilen AutocompletionRequest.origin'ye olan mesafesini metre cinsinden ifade eder.
• matched_substrings, açıklamada kullanıcının girişindeki öğelerle eşleşen bir dizi alt dize içeriyor. Bu, uygulamanızdaki 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, açıklama dizenin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
• place_id, bir yeri benzersiz şekilde tanımlayan metin tanımlayıcısıdır. Yerle ilgili bilgileri almak için bu tanımlayıcıyı Yer Ayrıntıları isteğinin placeId alanına iletin. Yer kimliğiyle bir yere referans verme hakkında daha fazla bilgi edinin.
• 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 dizenin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
  • Eşleşen terim: value

Aşağıdaki örnekte, "yakınımda pizza" ifadesi için bir sorgu tahmini isteği yürütülür ve sonuç bir listede gösterilir.

// 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;
index.ts

// 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;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Örneği görüntüleyin

Oturum jetonları

AutocompleteService.getPlacePredictions() Faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonlarını (uygulandıysa) kullanabilir. Oturum jetonları, kullanıcının otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcının sorgu yazmaya başlamasıyla başlar ve bir yer seçmesiyle sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir. Bir oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).

AutocompleteService.getPlacePredictions() çağrısından elde edilen yerle ilgili tek bir Yer Ayrıntıları isteğinde bulunmak için aynı oturum jetonunu kullanabilirsiniz. Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları isteğiyle birleştirilir ve çağrı, normal bir Yer Ayrıntıları isteği olarak ücretlendirilir. Otomatik tamamlama isteği ücretsizdir.

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şturma ve ardından bunu AutocompleteService içinde iletme gösterilmektedir (displaySuggestions() işlevi, kısa olması için çıkarılmıştır):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonun birden fazla oturumda kullanılması, her isteğin ayrı ayrı faturalandırılmasına neden olur.

Oturum jetonları hakkında daha fazla bilgi edinin.

Otomatik Tamamlama ve SearchBox widget'larını stilize etme

Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, Google Haritası'na dahil edilecek şekilde stillendirilir. 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.

Yer Adı Otomatik Tamamlama (Eski) optimizasyonu

Bu bölümde, Yer Otomatik Tamamlama (Eski) hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.

Genel kurallardan bazıları şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu şunları kullanmaktır: Maps JavaScript API Otomatik Yer Tamamlama (Eski) widget'ı, Android için Yerler SDK'sı Otomatik Yer Tamamlama (Eski) widget'ı, veya iOS için Yerler SDK'sı Otomatik Yer Tamamlama (Eski) kullanıcı arayüzü denetimi
• Temel Yer Otomatik Tamamlama (Eski) veri alanları hakkında en başından itibaren bilgi edinin.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
• API hata döndürürse uygulamanızın sorunsuz bir şekilde çalışmaya devam etmesini sağlamak için hata işlemeyi kullanın.
• Uygulamanızın seçim yapılmadığında durumu ele aldığından ve kullanıcılara devam etme olanağı sunduğundan emin olun.

Maliyet optimizasyonu ile ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Yer Otomatik Tamamlama (Eski) hizmetinin kullanım maliyetini optimize etmek için Yer Ayrıntıları (Eski) ve Yer Otomatik Tamamlama (Eski) widget'larında alan maskeleri kullanarak yalnızca ihtiyacınız olan yer verileri alanlarını döndürün.

Gelişmiş maliyet optimizasyonu

İstek başına fiyatlandırmaya erişmek için Place Autocomplete (Eski) hizmetini programatik olarak uygulamayı düşünebilir ve Yer Ayrıntıları (Eski) yerine seçilen yerle ilgili Geocoding API sonuçları isteyebilirsiniz. Aşağıdaki koşulların her ikisi de karşılanıyorsa Geocoding API ile birlikte kullanılan İstek Başına fiyatlandırma, Oturum Başına (oturum tabanlı) fiyatlandırmaya kıyasla daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresi gerekiyorsa Geocoding API, bu bilgileri Yer Ayrıntıları (Eski) çağrısından daha düşük bir maliyetle sağlar.
• Kullanıcılar, ortalama dört veya daha az Yer Otomatik Tamamlama (Eski) tahmin isteği içinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmaya göre daha uygun maliyetli olabilir.

Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında herhangi bir bilgi gerektiriyor mu?

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde, Yer Otomatik Tamamlama (Eski) performansını optimize etmenin yolları açıklanmaktadır:

• Yer Otomatik Tamamlama (Eski) uygulamanıza ülke kısıtlamaları, konum önyargısı ve (programatik uygulamalar için) dil tercihi ekleyin. Dil tercihi, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini aldıkları için widget'larda gerekli değildir.
• Yer Otomatik Tamamlama (Eski) özelliğine harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcının Yer Otomatik Tamamlama (Eski) 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 bilgisi gireceğini düşünüyorsanız Coğrafi Kodlama API'sine yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yerle ilgili sorguları ada veya adrese göre girmesini bekliyorsanız Yer Bulma (Eski) isteği kullanın. Sonuçların yalnızca belirli bir bölgede beklenmesi durumunda konum önyargısı özelliğini kullanın.
  Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
  • Kullanıcılar, bir bina içindeki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini girerken. Örneğin, "Stroupežnického 3191/17, Praha" Çek adresinde Yer Otomatik Tamamlama (Eski) özelliğiyle kısmi tahmin elde edilir.
  • New York City'de "23-30 29th St, Queens" veya Hawai'i'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresleri giren kullanıcılar.

Kullanım sınırları

Kotalar

Kota ve fiyatlandırma bilgileri için Places API'nin Kullanım ve Faturalandırma dokümanlarına bakın.