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ının önceden yazma davranışını sağlamak için otomatik tamamlama özelliğini kullanabilirsiniz. Otomatik tamamlama hizmeti; yer adları, adresler ve artı kodları çözümlenerek tam kelimeler ve alt dizelerle eşleşebilir. Böylece uygulamalar, anında yer tahminleri sağlamak için kullanıcı yazarken sorgu gönderebilir.

Kullanmaya başlama

Maps JavaScript API'de Yerler kitaplığını kullanmadan önce, ilk olarak Maps JavaScript API için oluşturduğunuz projede, Google Cloud Console'da Places API'nin etkinleştirildiğinden emin olun.

Etkin API'ler listenizi 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 arayın.
  4. Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
    2. Places API'yi arayın ve sonuçlar listesinden seçin.
    3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Places API görünür.

Kitaplık yükleniyor

Yerler hizmeti, ana Maps JavaScript API kodundan ayrı olan bağımsız bir kitaplıktır. Bu kitaplıkta yer alan işlevi kullanmak için önce Maps API önyükleme URL'sindeki libraries parametresini kullanarak bu işlevi yüklemeniz gerekir:

<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ış konusuna bakın.

Sınıfların özeti

API, sırasıyla Autocomplete ve SearchBox sınıfları aracılığıyla ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar. Ayrıca, otomatik tamamlama sonuçlarını programlı bir şekilde almak için AutocompleteService sınıfını kullanabilirsiniz (Haritalar JavaScript API Referansı: AutocompleteService sınıfı'na bakın).

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

  • Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metin girdiğinde otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde döndürür. Kullanıcı listeden bir yer seçtiğinde, bu yerle ilgili bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz.
    Bir otomatik tamamlama metin alanı ve kullanıcı arama sorgusunu girerken sunulan yer tahminlerinin seçim listesi.
    Şekil 1: Metin alanını ve seçim listesini otomatik doldurma
    Doldurulmuş adres formu.
    Şekil 2: Doldurulmuş adres formu
  • SearchBox, Autocomplete ile hemen hemen aynı şekilde bir metin giriş alanı ekler. Farklar aşağıda belirtilmiştir:
    • Başlıca fark, seçim listesinde gösterilen sonuçlardadır. SearchBox, yerleri (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizza şubelerinin adları yer alabilir.
    • SearchBox, aramayı kısıtlamak için Autocomplete seçeneğinden daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds değerine göre yönlendirebilirsiniz. İkinci seçenekte, aramayı belirli bir ülke ve belirli yer türleriyle sınırlandırabilir ve sınırları ayarlayabilirsiniz. Daha fazla bilgi için aşağıdaki bilgilere göz atın.
    Doldurulmuş adres formu.
    Şekil 3: Arama Kutusu arama terimleri ve yer tahminleri sunar.
    Aşağıda ayrıntıları inceleyin.
  • Tahminleri programatik olarak almak için AutocompleteService nesnesi oluşturabilirsiniz. Eşleşen yerleri almak için getPlacePredictions() numaralı telefonu arayın veya eşleşen yerleri ve önerilen arama terimlerini almak için getQueryPredictions() numaralı telefonu arayın. Not: AutocompleteService herhangi bir kullanıcı arayüzü denetimi eklemez. Bunun yerine, yukarıdaki yöntemler bir dizi tahmin nesneleri döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgileri ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.

Otomatik Tamamlama widget'ı ekleme

Autocomplete widget'ı web sayfanızda bir metin giriş alanı oluşturur, kullanıcı arayüzü seçim listesindeki yerlerle ilgili tahminleri sağlar ve getPlace() isteğine yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her bir giriş tek bir yere karşılık gelir (Places API tarafından tanımlandığı şekilde).

Autocomplete kurucusu iki bağımsız değişken alır:

  • text türünde bir HTML input öğesi. Bu, otomatik tamamlama hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.
  • Aşağıdaki özellikleri içerebilen isteğe bağlı bir AutocompleteOptions bağımsız değişkeni:
    • Kullanıcının seçilen PlaceResult için Place Details yanıtına dahil edilecek fields veri dizisi. Özellik ayarlanmazsa veya ['ALL'] aktarılırsa kullanılabilir tüm alanlar döndürülür ve ücretlendirilir (bu, üretim dağıtımları için önerilmez). Alanların listesi için PlaceResult bölümünü inceleyin.
    • Desteklenen türlerde listelendiği gibi açık bir türü veya tür koleksiyonunu belirten bir types dizisi. Tür belirtilmezse tüm türler döndürülür.
    • bounds, yerlerin aranacağı alanı belirten bir google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere yönlüdür, ancak bunlarla sınırlı değildir.
    • strictBounds, API'nin yalnızca belirtilen bounds ile tanımlanan bölgede bulunan yerleri döndürmesi gerekip gerekmediğini belirten bir boolean öğesidir. API, kullanıcı girişiyle eşleşse bile bu bölgenin dışındaki sonuçları döndürmez.
    • componentRestrictions, sonuçları belirli gruplarla kısıtlamak için kullanılabilir. Şu anda componentRestrictions kullanarak en fazla 5 ülkeye göre filtreleyebilirsiniz. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Ülke kodlarının bir listesi olarak birden çok ülke iletilmelidir.

      Not: Ülke koduyla birlikte beklenmedik sonuçlar alırsanız hedeflediğiniz ülkeleri, bağımlı bölgeleri ve özel coğrafi bölgeleri içeren bir kod kullandığınızı doğrulayın. Kod bilgilerini Wikipedia: ISO 3166 ülke kodlarının listesi veya ISO Çevrimiçi Tarama Platformu'nda bulabilirsiniz.

    • placeIdOnly, Autocomplete widget'ına yalnızca yer kimliklerini alması talimatını vermek için kullanılabilir. Autocomplete nesnesinde getPlace() çağrılırken, kullanıma sunulan PlaceResult yalnızca place id, types ve name özellikleri ayarlanır. Döndürülen yer kimliğini Yerler, Coğrafi Kodlama, Yol Tarifi veya Mesafe Matrisi hizmetlerine yapılan çağrılarda kullanabilirsiniz.

Otomatik Tamamlama tahminlerini kısıtlama

Varsayılan olarak Yer Otomatik Tamamlama, kullanıcının bulunduğu konumun yakınındaki tahminler için eğilimli olacak şekilde tüm yer türlerini sunar ve kullanıcının seçtiği yer için mevcut tüm veri alanlarını getirir. Kullanım alanınıza dayalı olarak daha alakalı tahminler sunmak için Yer Otomatik Tamamlama seçeneklerini ayarlayın.

Yapım aşamasında seçenekleri belirleyin

Autocomplete oluşturucu, widget oluşturma sırasında kısıtlamalar ayarlamak için bir AutocompleteOptions parametresini kabul eder. Aşağıdaki örnekte, establishment türü yerler istemek için bounds, componentRestrictions ve types seçenekleri belirtilmektedir. Bu seçenekler, belirtilen coğrafi bölgedeki yerler için tercih edilir ve tahminleri yalnızca ABD içindeki yerlerle sınırlandırılır. fields seçeneğinin ayarlanması, kullanıcının seçilen yerle ilgili hangi bilgilerin döndürüleceğini belirtir.

Mevcut bir widget'ta bir seçeneğin değerini değiştirmek için setOptions() numaralı telefonu arayın.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

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

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

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

Otomatik tamamlama için ağırlıkları ve arama alanı sınırlarını tanımlayın

Aşağıdaki yöntemleri kullanarak otomatik tamamlama sonuçlarında yaklaşık bir konuma veya alana öncelik verebilirsiniz:

  • Autocomplete nesnesinin oluşturulması sırasında sınırları ayarlayın.
  • Mevcut bir Autocomplete öğesinin sınırlarını değiştirin.
  • Sınırları haritanın görüntü alanına ayarlayın.
  • Aramayı sınırlarla sınırlandırın.
  • Aramayı belirli bir ülkeyle sınırlandırın.

Önceki örnekte, oluşturma sırasındaki ayar sınırları gösterilmektedir. 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 üzerindeki arama alanını dikdörtgen sınırlarla değiştirmek için setBounds() işlevini ç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);
Sınırları haritanın görüntü alanına ayarlayın

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

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Haritanın görüntü alanındaki Otomatik Tamamlama tahminlerinin bağlantısını kaldırmak için unbind() 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örüntüleyin

Aramayı geçerli sınırlarla sınırla

Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre geçerli sınırlara göre kısıtlamak için strictBounds seçeneğini ayarlayın.

autocomplete.setOptions({ strictBounds: true });
Tahminleri belirli bir ülkeyle sınırlama

Otomatik tamamlama aramasını beş taneye kadar ülke içeren belirli bir grupla sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() numaralı telefonu çağırın.

TypeScript

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

JavaScript

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

Örneği görüntüleyin

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 bölümünde listelendiği gibi bir tür veya tür koleksiyonu belirtir. Herhangi bir kısıtlama belirtilmezse tüm türler döndürülür.

types seçeneğinin değeri veya setTypes() öğesine iletilen değer için aşağıdakilerden birini belirtebilirsiniz:

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

İstek aşağıdaki durumlarda reddedilir:

  • Beşten fazla tür belirtiyorsunuz.
  • Tanınmayan türleri belirtirsiniz.
  • Tablo 1 veya Tablo 2'deki herhangi bir türü, Tablo 3'teki herhangi bir filtreyle birlikte kullanabilirsiniz.

Yerler Otomatik Tamamlama demosu, farklı yer türleri arasında yapılan tahminler arasındaki farkları gösterir.

Demoyu ziyaret edin

Yer bilgileri alınıyor

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() değerini çağırın.
  2. Autocomplete nesnesinde Autocomplete.getPlace() yöntemini çağırarak PlaceResult nesnesini alın. Daha sonra bu nesneyi seçilen yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.

Varsayılan olarak bir kullanıcı bir yer seçtiğinde otomatik tamamlama, seçilen yer için mevcut tüm veri alanlarını döndürür ve buna göre faturalandırılırsınız. Döndürülecek yer verisi alanlarını belirtmek için Autocomplete.setFields() değerini kullanın. İsteyebileceğiniz yer verisi alanlarının listesi de dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() kullandığınızdan emin olun.

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

Adres formları için adresi yapılandırılmış biçimde almak faydalıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields() değerini çağırın ve address_components alanını belirtin.

Aşağıdaki örnekte, bir adres formundaki alanları doldurmak için otomatik tamamlama özelliği kullanılmaktadır.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

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

Widget görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larının stilini belirleme konusuna bakın.

SearchBox, kullanıcıların "İstanbul'da pizza" veya "İzmir Caddesi'ndeki ayakkabı mağazaları" gibi metne dayalı bir coğrafi arama gerçekleştirmesine olanak tanır. SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girildikçe hizmet, tahminleri açılır seçim listesi biçiminde döndürür.

SearchBox, yerleri (Place API tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "yeni bir pizza" yazarsa seçim listesinde "İstanbul'da pizza" ifadesi ve çeşitli pizzacıların adları yer alabilir. Bir kullanıcı listeden bir yer seçtiğinde, bu yer hakkındaki bilgiler SearchBox nesnesine döndürülür ve uygulamanız tarafından alınabilir.

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

  • text türünde bir HTML input öğesi. Bu, SearchBox hizmetinin sonuçlarını izleyip ekleyeceği giriş alanıdır.
  • bounds özelliğini içerebilen bir options bağımsız değişkeni: bounds, yerlerin aranacağı alanı belirten google.maps.LatLngBounds nesnesidir. Sonuçlar, bu sınırların içindeki yerlere dayalı olup bunlarla sınırlı değildir.

Aşağıdaki kod, sonuçları enlem/boylam koordinatlarıyla belirtilen belirli bir coğrafi alandaki yerlere göre ağırlıklandırmak için bounds parametresini kullanır.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

SearchBox için arama alanını değiştirme

Mevcut bir SearchBox öğesinin arama alanını değiştirmek için SearchBox nesnesinde setBounds() çağrısı yapın ve ilgili LatLngBounds nesnesini iletin.

Örneği görüntüleyin

Yer bilgileri alınıyor

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

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

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

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örüntüleyin

Widget görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larının stilini belirleme konusuna bakın.

Otomatik Yer Tamamlama Hizmeti tahminlerini programatik olarak alma

Tahminleri programatik olarak almak için AutocompleteService sınıfını kullanın. AutocompleteService, herhangi bir kullanıcı arayüzü kontrolü eklemez. Bunun yerine, her biri tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir tahmin nesneleri dizisi döndürür. Kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol sahibi olmak istiyorsanız bu yöntem yararlıdır.

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

  • getPlacePredictions() yer tahminlerini döndürür. Not: "Yer", Places API tarafından tanımlandığı şekliyle bir işletme, coğrafi konum veya önemli bir yer olabilir.
  • getQueryPredictions(), yerleri (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi döndürür. Örneğin, kullanıcı "pizza in new" yazarsa seçim listesinde "pizza in New York, NY" ifadesi ve çeşitli pizza restoranlarının adları yer alabilir.

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

  • description, eşleşen tahmindir.
  • distance_meters, yerin belirtilen AutocompletionRequest.origin ile arasındaki mesafenin metre cinsinden değeridir.
  • matched_substrings, açıklamada, kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içerir. Bu, bu alt dizeleri uygulamanızda vurgulamak için kullanışlıdır. Sorgu, çoğu durumda açıklama alanının bir alt dizesi olarak görünür.
    • length, alt dizenin uzunluğudur.
    • offset, açıklama dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
  • place_id, bir yeri benzersiz şekilde tanımlayan metin tanımlayıcıdır. Yer hakkında bilgi almak için bu tanımlayıcıyı Yer Ayrıntıları isteğinin placeId alanına iletin. Yer kimliğiyle bir yeri referans gösterme 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 dizesinin başlangıcından itibaren ölçülen ve eşleşen alt dizenin göründüğü karakter ofsetidir.
    • value eşleşen terim.

Aşağıdaki örnekte, "pizza yakınındaki" kelime öbeği için bir sorgu tahmini isteği yürütülmüştür ve sonuç bir listede görüntülenir.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

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örüntüleyin

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 tamamlama özelliğinin sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir. Bir oturum sonlandırıldıktan sonra jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).

AutocompleteService.getPlacePredictions() öğesine yapılan bir çağrıdan kaynaklanan yer hakkında tek bir Yer Ayrıntıları isteği göndermek için aynı oturum jetonunu kullanabilirsiniz. Bu durumda, otomatik tamamlama isteği Yer Ayrıntısı isteğiyle birleştirilir ve arama, normal Yer Ayrıntısı isteği olarak ücretlendirilir. Otomatik tamamlama isteği için ücret alınmaz.

Her yeni oturum için benzersiz bir oturum jetonu aktardığınızdan emin olun. Aynı jetonu birden fazla Otomatik Tamamlama oturumu için kullanmak, bu Otomatik Tamamlama oturumlarını geçersiz kılar ve geçersiz oturumlardaki tüm Otomatik Tamamlama istekleri, İstek Başına Otomatik Tamamlama SKU'su kullanılarak tek tek ücretlendirilir. Oturum jetonları hakkında daha fazla bilgi edinin.

Aşağıdaki örnekte, bir oturum jetonu oluşturulup daha sonra AutocompleteService içinde iletilmesi gösterilmektedir (displaySuggestions() işlevi kısa olması için atlanmıştır):

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

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

Her yeni oturum için benzersiz bir oturum jetonu aktardığınızdan emin olun. Aynı jetonu birden fazla oturumda kullanmak, her isteğin ayrı ayrı faturalandırılmasına neden olur.

Oturum jetonları hakkında daha fazla bilgi edinin.

Otomatik Tamamlama ve Arama Kutusu widget'larının stil özelliklerini ayarlama

Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, Google haritasına eklenmek üzere tasarlanmıştır. Stili kendi sitenize uygun şekilde ayarlayabilirsiniz. Aşağıdaki CSS sınıfları mevcuttur. Aşağıda listelenen tüm sınıflar, hem Autocomplete hem de SearchBox widget'ları için geçerlidir.

Otomatik Tamamlama ve SearchBox widget&#39;ları için CSS sınıflarını gösteren grafik
Otomatik tamamlama ve SearchBox widget'ları için CSS sınıfları
CSS sınıfı Açıklama
pac-container Otomatik Yer Tamamlama hizmeti tarafından döndürülen tahminlerin listesini içeren görsel öğe. Bu liste, Autocomplete veya SearchBox widget'ının altında bir açılır liste olarak görünür.
pac-icon Tahmin listesindeki her bir öğenin solunda gösterilen simge.
pac-item Autocomplete veya SearchBox widget'ı tarafından sağlanan tahmin listesindeki bir öğe.
pac-item:hover Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected Kullanıcı klavyeyle seçtiğinde öğe. Not: Seçilen öğeler bu sınıfın ve pac-item sınıfının üyesi olacak.
pac-item-query Tahminin ana parçası olan pac-item içindeki bir aralık. Coğrafi konumlar için "Sidney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. "İstanbul'da pizza" gibi metin tabanlı aramalarda, sorgunun tam metnini içerir. pac-item-query varsayılan olarak siyah renklidir. pac-item içinde ek metin varsa pac-item-query alanının dışındadır ve stilini pac-item öğesinden devralır. Varsayılan olarak gri renklidir. Ek metin genellikle bir adrestir.
pac-matched Döndürülen tahminin kullanıcı girişiyle eşleşen bölümü. Varsayılan olarak, bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin, pac-item sınırları içinde herhangi bir yerde olabileceğini unutmayın. Bu ülke mutlaka pac-item-query kapsamında olmayabilir ve hem pac-item-query içinde hem de kısmen pac-item içinde kalan metnin içinde olabilir.

Otomatik Yer Tamamlama optimizasyonu

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

Aşağıda bazı genel yönergeler verilmiştir:

  • Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu; Maps JavaScript API Otomatik tamamlama widget'ı, Android için Yerler SDK'sı Otomatik tamamlama widget'ı veya iOS için Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü kullanmaktır.
  • Otomatik Yer Tamamlama veri alanlarıyla ilgili temel bilgileri en baştan geliştirin.
  • Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlı olsa da otomatik tamamlama performansı üzerinde önemli etkileri olabilir.
  • API hata döndürürse uygulamanızın sorunsuz bir şekilde eskimesini sağlamak için hata işlemeyi kullanın.
  • Uygulamanızın seçim olmadığında işlemleri karşıladığından ve kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Yer Tamamlama hizmetini kullanma maliyetini optimize etmek için yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larında alan maskelerini kullanın.

Gelişmiş maliyet optimizasyonu

İstek Başına fiyatlandırma'ya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'sı sonuçlarını istemek için Yer Otomatik Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen İstek Başına fiyatlandırması, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

  • Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir tutar için sağlar.
  • Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
İhtiyaçlarınıza uygun Otomatik Yer Tamamlama uygulamasını seçme konusunda yardım için aşağıdaki soruya verdiğiniz yanıta karşılık gelen sekmeyi seçin.

Başvurunuzda, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerekiyor mu?

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Uygulamanız; yer adı, işletmenin durumu veya çalışma saatleri gibi Yer Ayrıntıları gibi yer ayrıntıları gerektirdiğinden, Otomatik Yer Tamamlama uygulamanızda, hangi yer verisi alanlarına bağlı olarak 0, 017 ABD doları tutarında oturum başına ve geçerli Yer Veri SKU'ları'nın toplam maliyetine sahip olmak üzere bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunur) kullanılmalıdır33}{/14

Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields parametresini belirtmeyi unutmayın.

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

  1. Yer Otomatik Tamamlama yanıtındaki yer kimliği
  2. 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 gerekir

Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak, Coğrafi Kodlama API'si, 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 ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonu en iyi uygulamalarının uygulanıp uygulanmadığına bağlı olarak değişiklik gösterir.

Aşağıdaki soruyu yanıtlamak için bir kullanıcının, uygulamanızda bir Otomatik Yer Tamamlama tahmini seçmeden önce ortalama kaç karakter girdiğini analiz edin.

Kullanıcılarınız ortalama dört veya daha az istekte Otomatik Yer Tamamlama tahminini seçiyor mu?

Evet

Otomatik Yer Tamamlama özelliğini, oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Coğrafi Kodlama API'sini çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Yer Otomatik Tamamlama - İstek Başına isteğinin maliyeti 0,01132 ABD dolarıdır. Dolayısıyla, dört isteğin ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu, oturum başına 0,017 ABD doları tutarındaki Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.1

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

Hayır

Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Kullanıcılar bir Otomatik Yer Tamamlama tahmini seçmeden önce yapılmasını beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama istekleriniz hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanmalıdır.Bu durumda, oturum başına toplam 0,017 ABD doları maliyet elde edilir.1

Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirtmeyi unutmayın.

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

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

Otomatik Yer Tamamlama isteklerini ertelemeyi düşünün
Uygulamanızın daha az istek yapması için Otomatik Yer Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejilerden yararlanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Yer Tamamlama isteklerinde bulunmak, kullanıcı yedi karakter yazıp bir Coğrafi Kodlama API'si isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 Otomatik Tamamlama + 0,005 Coğrafi Kodlama ABD doları).1

Geciken istekler, ortalama programatik isteğinizi dörde düşmesine neden oluyorsa Coğrafi Kodlama API'si ile performans gösteren Yer Otomatik Tamamlama uygulaması için yönergeleri uygulayabilirsiniz. Geciken isteklerin, her yeni tuş vuruşunda tahmin görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmaları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ı sayfasına bakın.

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansını optimize etme yöntemleri açıklanmaktadır:

  • Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, konuma ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtiğinden, dil tercihi gerekli değildir.
  • Otomatik Yer Tamamlama'yı bir harita içeriyorsa, konumu harita görüntü alanına göre taşıyabilirsiniz.
  • Kullanıcının Otomatik Tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığından, daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
    • Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API çağrısında orijinal kullanıcı girişini yeniden kullanın.
    • Kullanıcının belirli bir yer için ad veya adrese göre sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
    Coğrafi Kodlama API'sini kullanmayı en iyi açıklayan diğer senaryolar:
    • Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresleri giren kullanıcılar. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Yer Tamamlama'da kısmi bir tahmin sağlar.
    • New York'ta "23-30 29

Kullanım sınırları ve politikalar

Kotalar

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

Politikalar

Yerler Kitaplığı ve Maps JavaScript API'nin kullanımı, Place API için açıklanan politikalara uygun olmalıdır.