Place Autocomplete

Platform seçin: Android iOS JavaScript Web Hizmeti

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.

Etkin API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve 'ı tıklayın.
  3. Kontrol Paneli'ndeki API listesinde Places API'yi bulun.
  4. API'yi listede görüyorsanız hazırsınız demektir. API listede yoksa etkinleştirin:
    1. 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.
    2. Places API'yi arayıp sonuçlar listesinden seçin.
    3. 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:

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

Daha fazla bilgi için Kitaplıklara Genel Bakış sayfasını inceleyin.

Sınıfların özeti

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).

Aşağıda, kullanılabilen sınıfların özetini bulabilirsiniz:

  • 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.
    Otomatik tamamlama metin alanı ve kullanıcı arama sorgusuna girdikçe sağlanan yer tahminlerinin listesi.
    Şekil 1: Metin alanını otomatik tamamlama ve liste seçme
    Adres formunu doldurun.
    Ş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.
    Adres formunu doldurun.
    Ş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);

JavaScript

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);

Veri alanlarını belirtin

İ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.

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

Otomatik tamamlama için ön yargılar ve arama alanı sınırları tanımlayın

Aşağıdaki adımları uygulayarak otomatik tamamlama sonuçlarının yaklaşık konumunu veya alanını tercih edebilirsiniz:

  • Autocomplete nesnesinin oluşturulmasıyla ilgili sınırları belirleyin.
  • Mevcut bir Autocomplete ile ilgili sınırları değiştirin.
  • Haritanın görüntü alanına olan sınırları ayarlayın.
  • Aramayı sınırlarla sınırlandırın.
  • Aramayı belirli bir ülkeyle sınırlar.

Önceki örnek, oluşturma sırasında ayar sınırlarını göstermektedir. Aşağıdaki örneklerde diğer ağırlık verme teknikleri gösterilmektedir.

Mevcut bir otomatik tamamlamanın sınırlarını değiştirme

Mevcut bir Autocomplete alanındaki arama alanını dikdörtgen sınırlarla değiştirmek için setBounds() yöntemini çağırın.

TypeScript

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);

JavaScript

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);
Haritanın görüntü alanına yönelik sınırları ayarlayın

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

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Otomatik tamamlama tahminlerinin, haritanın görüntü alanındaki bağlantısını kaldırmak için unbind() işlevini kullanın.

TypeScript

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

JavaScript

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

Örneği göster

Aramayı mevcut sınırlarıyla kısıtla

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.

TypeScript

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

JavaScript

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

Örneği göster

Yer türlerini sınırla

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:

  • Tablo Türleri'nden Tablo 1'e 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']);
  • Tablo Türleri'nden Tablo 3'teki herhangi bir filtre. Tablo 3'ten yalnızca tek bir değer belirtebilirsiniz.

Aşağıdaki durumlarda istek reddedilir:

  • Beşten fazla tür belirtirsiniz.
  • Tanınmayan türleri belirtirsiniz.
  • Tablo 1 veya Tablo 2'deki tüm türleri, Tablo 3'teki tüm filtrelerle birleştirebilirsiniz.

Otomatik Yer Tamamlama demosu, farklı yer türleri arasındaki tahmin farklarını gösterir.

Demoyu ziyaret edin

Yer bilgilerini alma

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:

  1. place_changed etkinliği için bir etkinlik işleyici oluşturun ve Autocomplete nesnesine addListener() yöntemini kullanarak işleyiciyi ekleyin.
  2. 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ında description 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();
}

JavaScript

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;

Örneği göster

Yer tutucu metni özelleştirme

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.

Widget görünümünü özelleştirmek için Otomatik tamamlama ve SearchBox widget'larının stilini belirleme başlıklı makaleye bakın.

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.

Örneği göster

Yer bilgilerini alma

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);
});

JavaScript

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

Örneği göster

Widget görünümünü özelleştirmek için Otomatik tamamlama ve SearchBox widget'larının stilini belirleme başlıklı makaleye bakın.

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.
  • place_id, bir yeri benzersiz şekilde tanımlayan metinsel bir tanımlayıcıdır. Yer hakkında bilgi almak için bir Yer Ayrıntıları isteğinin placeId alanına bu tanımlayıcıyı iletin. Yer kimliği kullanarak 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, 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;

JavaScript

// 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;

CSS

HTML

<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>

Örneği Deneyin

Örneği göster

Oturum jetonları

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.

Oturum jetonları hakkında daha fazla bilgi edinin.

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&#39;ları için CSS sınıflarının grafik çizimi
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.

Bazı genel yönergeler şunlardır:

  • Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Otomatik tamamlama widget'ını, Android için Yerler SDK'sını iOS tamamlama widget'ı veya iOS için Yerler SDK'sını kullanmaktır Otomatik tamamlama kullanıcı arayüzü denetimi
  • 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?

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntılarıyla oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gerektirdiğinden, Yer Otomatik Tamamlama uygulamanızda oturum başına (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak) toplam 0,017 ABD doları maliyet ve geçerli Yer Veri SKU'ları bulunmalıdır (istediğiniz yer verisi alanlarına bağlı olarak}}

Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahmindeki hem Yer Otomatik Tamamlama istekleri hem de Yer Ayrıntıları isteği dahildir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları'nı isterken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtından yer kimliği
  2. Yer Otomatik Tamamlama isteğinde kullanılan oturum jetonu
  3. İhtiyacınız olan yer verisi alanlarını belirten fields parametresi

Hayır, yalnızca adres ve konum gerekiyor

Coğrafi Kodlama API'sı, Yer Otomatik Tamamlama kullanımınızın performansına bağlı olarak, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın otomatik tamamlama verimliliği, kullanıcıların yazdıklarına, kullanıldığı yere ve performans optimizasyonuyla ilgili en iyi uygulamaların uygulanıp uygulanmadığına bağlı olarak değişir.

Aşağıdaki soruyu yanıtlamak için, kullanıcının uygulamanızda otomatik yerleştirme tahmini seçmeden önce ortalama olarak kaç karakter girdiğini analiz edin.

Kullanıcılarınız otomatik olarak ortalama dört veya daha az istekte Yer Otomatik Tamamlama tahmini seçer mi?

Evet

Yer otomatik tamamlamayı, oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Geocoding API'yi çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresleri ve enlem/boylam koordinatlarını sunar. Dört Yer Otomatik Tamamlama - İstek Başına istek yapmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, dört yer isteğinin ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti, oturum başına 0,017 ABD doları olan oturum başına otomatik tamamlama fiyatından 0,01632 ABD doları olur.1

Kullanıcılarınızın aradıkları tahmini daha da az sayıda karakterle almasına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

Hayır

Yer Ayrıntılarıyla oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Bir kullanıcı otomatik yer tahmini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırma maliyetini aştığından Yer Otomatik Tamamlama kullanımınız, hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için toplam oturum başına 0,017 ABD doları şeklinde bir oturum jetonu kullanmalıdır. 1

Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahmindeki hem Yer Otomatik Tamamlama istekleri hem de Yer Ayrıntıları isteği dahildir. Yalnızca Temel Veri alanları istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları'nı isterken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtından yer kimliği
  2. Yer Otomatik Tamamlama isteğinde kullanılan oturum jetonu
  3. Adres ve geometri gibi Temel Veriler alanlarını belirten fields parametresi

Yer Otomatik Tamamlama isteklerini ertelemeyi göz önünde bulundurun
Kullanıcının otomatik olarak ilk üç veya dört karakter girene kadar Yer Otomatik Tamamlama isteğini geciktirme gibi stratejiler uygulayabilirsiniz. Böylece uygulamanız daha az istek gönderebilir. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteklerinde bulunursa, kullanıcı yedi karakter yazar ve bir Geocoding API isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * 0,00283 İstek Başına Otomatik Tamamlama + 0,005 Coğrafi Kodlama).1

Gecikme istekleri, ortalama programatik isteğinizi dört değerin altına düşebiliyorsa Geocoding API ile yüksek performanslı otomatik yer tamamlama uygulamasına yönelik yönergeleri uygulayabilirsiniz. Gecikme isteklerinin, her yeni tuş vuruşunda tahminleri görmeyi bekleyecek kullanıcılar tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha az karakterden almasına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.


  1. Burada listelenen maliyetler ABD doları cinsindendir. Tam fiyatlandırma bilgileri için lütfen Google Haritalar Platformu Faturalandırması'na bakın.

Performansla ilgili en iyi uygulamalar

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.

Kullanım sınırları ve politikalar

Kotalar

Kota ve fiyatlandırma bilgileri için Yerler API'sinin Kullanım ve Faturalandırma belgelerine bakın.

Politikalar

Yerler Kitaplığı'nın kullanımı için Maps JavaScript API, Places API'si için açıklanan politikalara uygun olmalıdır.