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 yazmayla arama davranışını kazandırmak için otomatik tamamlamayı kullanabilirsiniz. Otomatik tamamlama hizmeti, tam kelimeler ve alt dizelerle eşleşerek yer adlarını, adresleri ve Plus Code'ları çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken sorgu göndererek anında yer tahminleri sağlayabilir. Places API tarafından tanımlandığı şekliyle, "yer" bir kuruluş, coğrafi konum veya önemli bir yer olabilir.

Başlarken

Maps JavaScript API'deki Yerler kitaplığını kullanmadan önce, Google Cloud Konsolu'nda, Maps JavaScript API için oluşturduğunuz projede Yerler API'sinin etkinleştirildiğinden emin olun.

Etkin 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 oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
  3. Kontrol panelindeki API listesinde Places API'yi bulun.
  4. API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında API'yi etkinleştir'i seçerek Kitaplık sekmesini görüntüleyin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
    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ığı yükleme

Yerler hizmeti, ana Maps JavaScript API kodundan ayrı, kendi kendine yeten bir kitaplıktır. Bu kitaplıktaki işlevleri kullanmak için öncelikle Haritalar API'nin önyükleme URL'sindeki libraries parametresini kullanarak kitaplığı 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ı aracılığıyla 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ı).

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

  • Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanda karakter girişlerini izler. Kullanıcı metin girerken otomatik tamamlama, yer tahminlerini açılır seçim listesi biçiminde 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.
    Otomatik tamamlama metin alanı ve kullanıcı arama sorgusunu girerken sağlanan yer tahminlerinin seçim listesi.
    Şekil 1: Otomatik tamamlama metin alanı ve seçim listesi
    Doldurulmuş bir adres formu.
    Şekil 2: Doldurulmuş adres formu
  • SearchBox, Autocomplete ile hemen hemen aynı şekilde web sayfanıza bir metin giriş alanı ekler. Farklar şunlardır:
    • Ana fark, seçim listesinde görünen sonuçlardadır. SearchBox, yerler (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir.
    • SearchBox, aramayı kısıtlamak için Autocomplete'e kıyasla daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds'ye yönlendirebilirsiniz. İkincisinde, 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.
    Doldurulmuş bir adres formu.
    Şekil 3: Arama kutusu, arama terimlerini ve yer tahminlerini gösterir.
    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()'ü, eşleşen yerlerin yanı sıra önerilen arama terimlerini almak için getQueryPredictions()'ü çağırın. Not: AutocompleteService, kullanıcı arayüzü denetimi eklemez. Bunun yerine, yukarıdaki yöntemler bir tahmin nesnesi dizisi döndürür. Her tahmin nesnesi, tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğiyle ilgili 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 listesinde yer alan yerlerle ilgili tahminler sağlar ve getPlace() isteğiyle yanıt olarak yer ayrıntılarını döndürür. Seçim listesindeki her giriş tek bir yere (Yerler API'si tarafından tanımlandığı şekilde) karşılık gelir.

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

  • text türündeki 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. Mülk ayarlanmazsa veya ['ALL'] iletilirse mevcut 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 başlıklı makaleyi inceleyin.
    • Desteklenen türler bölümünde listelenen 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 nesnesi. Sonuçlar bu sınırlar içinde bulunan yerlere yöneliktir ancak bunlarla sınırlı değildir.
    • strictBounds, API'nin yalnızca belirli bounds tarafından tanımlanan bölgedeki yerleri döndürmesi gerekip gerekmediğini belirten bir boolean bağımsız değişkenidir. 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. Şu anda componentRestrictions'yi kullanarak en fazla 5 ülkeye göre filtreleme yapabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir. Birden fazla ülke, ülke kodları listesi olarak iletilmelidir.

      Not: Bir ülke koduyla beklenmedik sonuçlar alırsanız hedeflediğiniz ülkeleri, bağlı bölgeleri ve coğrafi açıdan ilgi çekici özel alanları içeren bir kod kullandığınızdan emin olun. Kod bilgilerini Wikipedia: ISO 3166 ülke kodları listesi veya ISO Online Tarama Platformu'nda bulabilirsiniz.

    • placeIdOnly, Autocomplete widget'ına yalnızca yer kimliklerini döndürmesini bildirmek için kullanılabilir. Autocomplete nesnesi üzerinde getPlace() çağrıldığında, kullanıma sunulan PlaceResult'de yalnızca place id, types ve name özellikleri ayarlanır. Döndürülen yer kimliğini; Yerler, Coğrafi Kodlama, Yol Tarifleri 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 konumuna yakın tahminlere göre ağırlıklandırılmış 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.

Oluşturma sırasında seçenekleri ayarlama

Autocomplete kurucusu, widget oluşturulurken kısıtlamalar belirlemek için bir AutocompleteOptions parametresi kabul eder. Aşağıdaki örnekte, bounds, componentRestrictions ve types seçenekleri establishment türündeki yerleri isteyecek şekilde ayarlanmıştır. Bu örnekte, belirtilen coğrafi alandaki yerler tercih edilir ve tahminler yalnızca ABD'deki yerlerle sınırlandırılır. fields seçeneğini ayarlamak, kullanıcının seçtiği yerle ilgili hangi bilgilerin döndürüleceğini belirtir.

Mevcut bir widget için bir seçeneğin değerini değiştirmek üzere setOptions() işlevini ç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);
index.ts

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

index.js

Veri alanlarını belirtme

İhtiyacınız olmayan Places Veri SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions içine fields özelliğini ekleyin veya mevcut bir Autocomplete nesnesinde setFields()'yi ç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 konum veya bölgeyi tercih edecek şekilde aşağıdaki yöntemlerle yönlendirebilirsiniz:

  • Autocomplete nesnesi oluşturulurken sınırları ayarlayın.
  • Mevcut bir Autocomplete'teki sınırları değiştirin.
  • Sınırları haritanın görüntü alanına ayarlayın.
  • Aramayı sınırlarla kısıtlayın.
  • Aramayı belirli bir ülkeyle sınırlayın.

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

Mevcut bir Otomatik Tamamlama'nın sınırlarını değiştirme

Mevcut bir Autocomplete'daki arama alanını dikdörtgen sınırlar olarak 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);
index.ts

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

index.js
Sınırları haritanın görüntü alanına ayarlama

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

TypeScript

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

JavaScript

autocomplete.bindTo("bounds", map);

index.js

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

TypeScript

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

JavaScript

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ırlarla kısıtlama

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

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

Otomatik tamamlama aramasını en fazla beş ülkeyle sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() işlevini çağırın.

TypeScript

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

JavaScript

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() işlevini çağırın. Bu kısıtlama, Yer Türleri bölümünde listelenen 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()'a iletilen değer için aşağıdakilerden 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 bölümündeki Tablo 3'teki herhangi bir filtre Tablo 3'ten yalnızca tek bir değer 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 herhangi bir filtreyle karıştırırsınız.

Yerler Otomatik Tamamlama demosu, farklı yer türleri arasındaki tahmin farklılıklarını gösterir.

Demoyu ziyaret edin

Yer bilgilerini 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. Autocomplete nesnesinde Autocomplete.getPlace() çağrısı yaparak PlaceResult nesnesi alın. Bu nesneyi, seçili yer hakkında daha fazla bilgi edinmek için kullanabilirsiniz.

Varsayılan olarak, 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 size buna göre faturalandırılırsınız. Hangi yer veri alanlarının döndürüleceğini belirtmek için Autocomplete.setFields() türünü kullanın. İsteyebilirsiniz yer veri alanlarının listesi dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmaktan kaçınmak amacıyla, yalnızca kullanacağınız yer verilerini belirtmek için Autocomplete.setFields() kullandığınızdan emin olun.

name mülkü, Yerler 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 yararlıdır. Seçilen yerin yapılandırılmış adresini döndürmek için Autocomplete.setFields() işlevini çağırın ve address_components alanını belirtin.

Aşağıdaki örnekte, adres formunda alanları doldurmak için otomatik doldurma ö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();
}
index.ts

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;

index.js

Örneği görüntüleyin

Yer tutucu metni özelleştirme

Otomatik tamamlama hizmeti tarafından oluşturulan metin alanı varsayılan olarak standart yer tutucu metni 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 metni 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 lütfen yerelleştirme ile ilgili dokümanları okuyun.

Widget'ın görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larına stil uygulama başlıklı makaleyi inceleyin.

SearchBox, kullanıcıların "New York'ta pizza" veya "robson street yakınındaki ayakkabı mağazaları" gibi metne dayalı coğrafi aramalar yapmasına olanak tanır. SearchBox öğesini bir metin alanına ekleyebilirsiniz. Metin girilirken hizmet, açılır seçim listesi biçiminde tahminler döndürür.

SearchBox, yerler (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir. Kullanıcı listeden bir yer seçtiğinde, söz konusu yerle ilgili 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ündeki bir HTML input öğesi. Bu, SearchBox hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.
  • bounds mülkünü içerebilen bir options bağımsız değişkeni: bounds, yerlerin aranacağı alanı belirten bir google.maps.LatLngBounds nesnesi. Sonuçlar bu sınırlar dahilindeki yerlere yöneliktir ancak bunlarla sınırlı değildir.

Aşağıdaki kod, sonuçları enlem/boylam koordinatları aracılığıyla belirtilen belirli bir coğrafi bölgedeki yerlere yönlendirmek 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 nesnesinin arama alanını değiştirmek için SearchBox nesnesinde setBounds() işlevini çağırın ve ilgili LatLngBounds nesnesini iletin.

Örneği görüntüleyin

Yer bilgilerini alma

Kullanıcı arama kutusuna eklenmiş 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() işlevini çağırabilirsiniz.

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

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

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

Örneği görüntüleyin

Widget'ın görünümünü özelleştirmek için Otomatik Tamamlama ve Arama Kutusu widget'larına stil uygulama başlıklı makaleyi inceleyin.

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 tahminin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğiyle ilgili ayrıntıları içeren bir tahmin nesnesi dizisi döndürür. Bu, kullanıcı arayüzü üzerinde yukarıda açıklanan Autocomplete ve SearchBox tarafından sunulandan daha fazla kontrol sahibi olmak istiyorsanız faydalıdır.

AutocompleteService aşağıdaki yöntemleri gösterir:

  • getPlacePredictions(), yer tahminlerini döndürür. Not: "Yer", Places API tarafından tanımlandığı üzere bir kuruluş, coğrafi konum veya önemli bir yer olabilir.
  • getQueryPredictions(), konumları (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ı "pizza in new" (yeni pizza) yazarsa seçim listesinde "pizza in New York, NY" (New York, NY'de pizza) ifadesi ve çeşitli pizzacıların adları yer alabilir.

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

  • description, eşleşen tahmindir.
  • distance_meters, belirtilen AutocompletionRequest.origin'a olan mesafeyi (metre cinsinden) gösterir.
  • matched_substrings, açıklamada kullanıcının girişindeki öğelerle eşleşen bir dizi alt dize içerir. Bu, uygulamanızdaki bu alt dizelerin vurgulanması 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öründüğü açıklama dizenin başlangıcından itibaren ölçülen karakter ofsetidir.
  • place_id, bir yeri benzersiz şekilde tanımlayan metin tabanlı bir tanımlayıcıdır. Yerle ilgili bilgileri almak için bu tanımlayıcıyı Yer Ayrıntıları isteğinin placeId alanına gönderin. Yer kimliğiyle bir yere referans verme hakkında daha fazla bilgi edinin.
  • terms, sorgunun öğ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öründüğü açıklama dizenin başlangıcından itibaren ölçülen karakter ofsetidir.
    • value, eşleşen terimdir.

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.

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

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

CSS

style.css

HTML

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

Örneği görüntüleyin

Oturum jetonları

AutocompleteService.getPlacePredictions(), faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonlarını (uygulanmışsa) 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ı 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 bulunabilir. 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ını 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 yerde 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ıları isteğiyle birleştirilir ve çağrı 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 gönderdiğinizden emin olun. Aynı jetonun birden fazla Otomatik Tamamlama oturumunda kullanılması, 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, bir oturum jetonunun oluşturulması ve ardından bir AutocompleteService içinde iletilmesi gösterilmektedir (displaySuggestions() işlevi kısalık 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 gönderdiğinizden emin olun. Aynı jetonun birden fazla oturumda kullanılması, her isteğinin ayrı ayrı faturalandırılmasına neden olur.

Oturum jetonları hakkında daha fazla bilgi edinin.

Otomatik Tamamlama ve Arama Kutusu widget'larına stil uygulama

Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri bir Google haritasına eklenecek şekilde biçimlendirilir. 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.

Otomatik Tamamlama ve Arama Kutusu widget&#39;ları için CSS sınıflarının grafiksel bir gösterimi
Otomatik Tamamlama ve Arama Kutusu 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 Tahminler listesinde her öğenin solunda gösterilen simge.
pac-item Autocomplete veya SearchBox widget'ı tarafından sağlanan tahminler listesinde bir öğe.
pac-item:hover Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected Kullanıcının klavyeyle seçtiği öğe. Not: Seçilen öğeler bu sınıfın ve pac-item sınıfının üyesi olur.
pac-item-query Tahminin ana kısmı olan pac-item içindeki bir span. Coğrafi konumlar için bu alan, "Sydney" 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. pac-item-query varsayılan olarak siyah renkle gösterilir. pac-item içinde ek metin varsa bu metin pac-item-query dışındadır ve stilini pac-item'ten devralır. Varsayılan olarak gri renklidir. Ek metin genellikle bir adrestir.
pac-matched Döndürülen tahminin, kullanıcının girişiyle eşleşen kısmı. Varsayılan olarak bu eşleşen metin kalın metinle vurgulanır. Eşleşen metnin pac-item içinde herhangi bir yerde olabileceğini unutmayın. Bu metin, pac-item-query'ün bir parçası olmayabilir ve kısmen pac-item-query'te, kısmen de pac-item'teki kalan metinde bulunabilir.

Yer Adı Otomatik Tamamlama optimizasyonu

Bu bölümde, yer otomatik 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'ını, Android için Yerler SDK'sı otomatik tamamlama widget'ını veya iOS için Yerler SDK'sı otomatik tamamlama kullanıcı arayüzü denetimini kullanmaktır.
  • Yer Otomatik Tamamlama için temel veri alanlarını baştan itibaren öğrenin.
  • Konum önyargısı ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
  • API hata döndürdüğünde uygulamanızın sorunsuz bir şekilde işlevini yitirmesini sağlamak için hata işleme özelliğini kullanın.
  • Uygulamanızın, seçim yapılmadığında kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Yer Otomatik 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 Yer Otomatik Tamamlama widget'larındaki alan maskelerini kullanın.

Gelişmiş maliyet optimizasyonu

İstek başına fiyatlandırmaya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API sonuçlarını istemek için Otomatik Yer Tamamlama'nın programatik olarak uygulanmasını değerlendirin. Geocoding API ile birlikte kullanılan istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılanıyorsa oturum başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

  • Kullanıcının seçtiği yerin yalnızca enlem/boylamına veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri bir Yer Ayrıntıları çağrısından daha kısa sürede sağlar.
  • 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 maliyetli olabilir.
İhtiyaçlarınıza uygun yer otomatik tamamlama uygulamasını seçmenize yardımcı olması için aşağıdaki soruya verdiğiniz yanıta karşılık gelen sekmeyi seçin.

Uygulamanızda, seçilen tahminin adresi ve enlem/boylam dışında başka bir bilgi gerekiyor mu?

Evet, daha fazla ayrıntı gerekiyor

Oturum tabanlı yer otomatik tamamlamayı Yer Ayrıntıları ile kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi yer ayrıntılarını gerektirdiğinden, Yer Otomatik Tamamlama uygulamanızda bir oturum jetonu (programlı olarak veya JavaScript, Android ya da iOS widget'larına yerleştirilmiş olarak) kullanılmalıdır.Bu durumda, oturum başına 0, 017 ABD doları ve istediğiniz yer verileri alanlarına bağlı olarak geçerli Yerler Verileri SKU'ları için toplam maliyet oluşur.1

Widget uygulama
Oturum yönetimi, JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Buna hem yer otomatik tamamlama istekleri hem de seçili tahmindeki 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 belirtmeyi unutmayın.

Programlı uygulama
Yer Otomatik Tamamlama isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları'nı talep ederken aşağıdaki parametreleri ekleyin:

  1. Otomatik Yer Tamamlama yanıtındaki 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 gereklidir.

Yer Otomatik Tamamlama kullanımınızın performansına bağlı olarak, uygulamanız için Yer Ayrıntıları'na kıyasla Coğrafi Kodlama API'si daha uygun maliyetli bir seçenek olabilir. Her uygulamanın otomatik tamamlama verimliliği, kullanıcıların ne girdiklerine, uygulamanın nerede kullanıldığına ve performans optimizasyonu en iyi uygulamaları uygulanıp uygulanmadığına bağlı olarak değişir.

Aşağıdaki soruyu yanıtlamak için uygulamanızda bir yer otomatik tamamlama tahmini seçmeden önce kullanıcının ortalama olarak kaç karakter yazdığını analiz edin.

Kullanıcılar, ortalama dört veya daha az istekte bir Yer Otomatik Tamamlama tahmini seçiyor mu?

Evet

Oturum jetonları olmadan Yer Otomatik Tamamlama'yı programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Place Autocomplete - Request Per isteği göndermek 0,01132 ABD doları maliyete sahiptir. Bu nedenle, dört istek ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu maliyet, oturum başına 0,017 ABD doları olan Otomatik Tamamlama oturumu başına fiyattan daha düşüktür.1

Kullanıcılarınızın aradıkları tahmini daha da az karakterle almasına yardımcı olmak için performansla ilgili en iyi uygulamaları kullanmayı düşünebilirsiniz.

Hayır

Yer Ayrıntıları ile oturum tabanlı yer otomatik tamamlamayı kullanın.
Kullanıcının bir Otomatik Yer Tamamlama tahminini seçmeden önce göndermenizi beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama uygulamanızda hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanılmalıdır.Bu durumda, toplam maliyet oturum başına 0,017 ABD dolarıdır.1

Widget uygulama
Oturum yönetimi, JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilmiştir. Buna hem yer otomatik tamamlama istekleri hem de seçili tahmindeki yer ayrıntıları isteği dahildir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programlı uygulama
Yer Otomatik Tamamlama isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları'nı talep ederken aşağıdaki parametreleri ekleyin:

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

Yer otomatik tamamlama isteklerini ertelemeyi düşünün
Uygulamanızın daha az istek göndermesi için kullanıcı ilk üç veya dört karakteri yazana kadar yer otomatik tamamlama isteğini erteleme gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Yer Otomatik Tamamlama isteği gönderirseniz kullanıcı yedi karakter yazıp bir tahmin seçerse ve bu tahmin için bir Geocoding API isteği gönderirseniz toplam maliyet 0,01632 ABD doları olur (4 * 0,00283 ABD doları istek başına otomatik tamamlama + 0,005 ABD doları coğrafi kodlama).1

İstekleri ertelemeniz ortalama programatik isteğinizin dörtten az olmasını sağlayabilirse Geocoding API ile performanslı Yer Adı Otomatik Tamamlama uygulamasıyla ilgili yönergeleri uygulayabilirsiniz. Geciken isteklerin, her yeni tuş vuruşuyla tahminler 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 elde etmelerine yardımcı olmak için performansla ilgili en iyi uygulamaları kullanabilirsiniz.

  1. Burada listelenen maliyetler ABD doları cinsindendir. Fiyatlandırmayla ilgili tüm bilgiler için lütfen Google Haritalar Platformu Faturalandırması sayfasına bakın.

Performansla ilgili en iyi uygulamalar

Aşağıdaki kurallarda, yer otomatik tamamlama performansını optimize etme yöntemleri açıklanmaktadır:

  • Yer Otomatik Tamamlama uygulamanıza ülke kısıtlamaları, konum önyargısı ve (programlı 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 gerekmez.
  • Yer Otomatik Tamamlama özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
  • 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ıdan 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 yerle ilgili ad veya adresle sorgu girmesini bekliyorsanız Yer Bul isteği kullanın. Sonuçların yalnızca belirli bir bölgede elde edilmesi bekleniyorsa konumlu önyargı kullanın.
    Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
    • Bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adresleri giren kullanıcılar Örneğin, Çek adres "Stroupežnického 3191/17, Praha", Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
    • New York City'de "23-30 29th St, Queens" veya Hawai'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleriyle adres giren kullanıcılar.

Kullanım sınırları ve politikaları

Kotalar

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

Politikalar

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