Yer Adı Otomatik Tamamlama (Eski)

Giriş

Otomatik tamamlama, Maps JavaScript API'deki Places kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının ileriye doğru yazarak 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, anında yer tahminleri sağlamak için kullanıcı yazarken sorgu gönderebilir. Places API'de tanımlandığı gibi, "yer" bir işletme, coğrafi konum veya önemli bir yer olabilir.

Başlarken

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

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çip Aç'ı 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. Ancak bu proje eski durumundadır. Eski aşaması ve eski hizmetlerden daha yeni hizmetlere geçiş hakkında daha fazla bilgi için Eski ürünler ve özellikler başlıklı makaleyi inceleyin. Places API'de (Yeni) henüz GA ürünü olarak sunulmayan Autocomplete ve SearchBox widget'ları için bir istisna mevcuttur.

Kitaplığı yükleme

Places hizmeti, ana Maps JavaScript API kodundan ayrı, bağımsız bir kitaplıktır. Bu kitaplıkta bulunan özellikleri kullanmak için önce Maps API ö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ış sayfasını inceleyin.

Sınıfların özeti

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

Aşağıda, mevcut sınıfların bir özeti verilmiştir:

• Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alanı karakter girişleri için izler. Kullanıcı metin girerken otomatik tamamlama, açılır liste biçiminde yer tahminleri döndürür. Kullanıcı listeden bir yer seçtiğinde, yerle ilgili bilgiler otomatik tamamlama nesnesine döndürülür ve uygulamanız tarafından alınabilir. Ayrıntıları aşağıda bulabilirsiniz.

  

  

• SearchBox, Autocomplete ile hemen hemen aynı şekilde web sayfanıza bir metin giriş alanı ekler. Farklar şunlardır:
  • Temel fark, seçim listesinde görünen sonuçlardadır. SearchBox, yerleri (Places API tarafından tanımlandığı şekilde) ve önerilen arama terimlerini içerebilen genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı "pizza in new" yazarsa seçim listesinde "pizza in New York, NY" ifadesinin yanı sıra çeşitli pizza restoranlarının adları da yer alabilir.
  • SearchBox, aramayı kısıtlama konusunda Autocomplete kadar çok seçenek sunmaz. İlkinde, aramayı belirli bir LatLngBounds için önceliklendirebilirsiniz. İkincisinde, aramayı belirli bir ülke ve belirli yer türleriyle kısıtlayabilir, ayrıca sınırları belirleyebilirsiniz. Daha fazla bilgi için aşağıya bakın.

  

  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, eşleşen yerleri ve önerilen arama terimlerini almak için getQueryPredictions() yöntemini çağırın. Not: AutocompleteService, kullanıcı arayüzü kontrolleri eklemez. Bunun yerine, yukarıdaki yöntemler bir tahmin nesnesi dizisi döndürür. Her tahmin nesnesi, tahmin metninin yanı sıra referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içerir. Ayrıntıları aşağıda bulabilirsiniz.

Otomatik tamamlama widget'ı ekleme

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

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

• text türünde bir HTML input öğesi. Bu, otomatik tamamlama hizmetinin izleyeceği ve sonuçlarını ekleyeceği giriş alanıdır.
• Aşağıdaki özellikleri içerebilen isteğe bağlı bir AutocompleteOptions bağımsız değişkeni:
  • Kullanıcının seçtiği PlaceResult için Place Details yanıtına dahil edilecek bir veri dizisi fields. Özellik 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 sayfasına bakın.
  • Desteklenen türler bölümünde listelendiği gibi, açık bir tür veya tür koleksiyonu 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 içinde yer alan yerlere yöneliktir ancak bunlarla sınırlı değildir.
  • strictBounds, API'nin yalnızca verilen bounds tarafından tanımlanan bölge içinde yer alan yerleri döndürmesi gerekip gerekmediğini belirten bir boolean değeridir. 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. En fazla 5 ülkeye göre filtrelemek için componentRestrictions kullanabilirsiniz. Ülkeler, iki karakterli, ISO 3166-1 alfa-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ğımlı bölgeleri ve özel coğrafi alanları içeren bir kod kullandığınızı doğrulayın. Kod bilgilerini Wikipedia: ISO 3166 ülke kodları listesi veya ISO Online Browsing Platform'da bulabilirsiniz.

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

Otomatik tamamlama tahminlerini kısıtlama

Varsayılan olarak, Yer Adı Otomatik Tamamlama tüm yer türlerini sunar, kullanıcının konumuna yakın tahminler için 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 Adı Otomatik Tamamlama seçeneklerini ayarlayın.

Oluşturma sırasında 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ündeki yerleri istemek için bounds, componentRestrictions ve types seçenekleri ayarlanmıştır. Bu seçenekler, belirtilen coğrafi bölgedeki yerleri tercih eder ve tahminleri yalnızca ABD'deki yerlerle kısıtlar. fields seçeneğini ayarlamak, kullanıcının seçtiği yer hakkında hangi bilgilerin döndürüleceğini belirtir.

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

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

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

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

Veri alanlarını belirtme

İhtiyacınız olmayan Places Data SKU'ları için faturalandırılmamak üzere veri alanlarını belirtin. Önceki örnekte gösterildiği gibi, widget oluşturucuya iletilen AutocompleteOptions içine 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ımlama

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

• Autocomplete nesnesinin oluşturulmasıyla ilgili sınırları belirleyin.
• Mevcut bir Autocomplete için 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 kısıtlar.

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

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

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

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

autocomplete.setBounds(newBounds);
index.ts

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

autocomplete.setBounds(newBounds);
index.js

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

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.

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

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

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

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

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

Örneği görüntüleyin

Aramayı mevcut sınırlarla kısıtla

Sonuçları, harita görüntü alanına veya dikdörtgen sınırlara göre geçerli 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ş ülkeden oluşan belirli bir grupla sınırlamak için componentRestrictions seçeneğini kullanın veya setComponentRestrictions() yöntemini çağırın.

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

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

Örneği görüntüleyin

Yer türlerini kısıtlama

Tahminleri belirli yer türleriyle sınırlamak için types seçeneğini kullanın veya setTypes() yöntemini ç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() parametresine iletilen değer için şunlardan birini belirtebilirsiniz:

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

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

  veya:

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

• Yer Türleri'nden Tablo 3'teki 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 filtrelerle birleştirebilirsiniz.

Yer Adı Otomatik Tamamlama demosu, farklı yer türleri arasındaki tahmin farklılıklarını 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 için Autocomplete nesnesinde addListener() yöntemini çağırın.
2. Autocomplete nesnesinde Autocomplete.getPlace() yöntemini çağırarak PlaceResult nesnesini alın. Bu nesneyi kullanarak seçilen yer hakkında daha fazla bilgi edinebilirsiniz.

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() 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 Autocomplete.setFields() kullanarak yalnızca kullanacağınız yer verilerini belirttiğinizden emin olun.

name özelliği, Yer Adı Otomatik Tamamlama tahminlerinden description değerini içerir. description hakkında daha fazla bilgiyi Places Autocomplete belgelerinde bulabilirsiniz.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

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

window.initAutocomplete = initAutocomplete;
index.js

Örneği görüntüleyin

Yer tutucu metni özelleştirme

Varsayılan olarak, otomatik tamamlama hizmeti tarafından oluşturulan metin alanı standart yer tutucu metin içerir. Metni değiştirmek için input öğesinde placeholder özelliğini ayarlayın:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Not: Varsayılan yer tutucu metin otomatik olarak yerelleştirilir. Kendi yer tutucu değerinizi belirtirseniz uygulamanızda bu değerin yerelleştirmesini yapmanız gerekir. Google Haritalar JavaScript API'nin kullanılacak dili nasıl seçtiği hakkında bilgi edinmek için yerelleştirme ile ilgili belgeleri okuyun.

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

Arama kutusu widget'ı ekleme

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

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

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

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

Aşağıdaki kod, sonuçları enlem/boylam koordinatları kullanılarak 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 için arama alanını değiştirmek istiyorsanız SearchBox nesnesinde setBounds() yöntemini çağırı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. SearchBox nesnesinde getPlaces() yöntemini çağırarak her biri PlaceResult nesnesi olan birkaç tahmin içeren bir dizi alabilirsiniz.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.js

Örneği görüntüleyin

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

Yer Adı Otomatik 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 tahmin metnini, referans bilgilerini ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntıları içeren bir tahmin nesnesi 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öntemden yararlanabilirsiniz.

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

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

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

• description, eşleşen tahmindir.
• distance_meters, yerin belirtilen AutocompletionRequest.origin değerine olan metre cinsinden mesafesidir.
• matched_substrings, açıklamada kullanıcının girişindeki öğelerle eşleşen bir alt dize grubu içeriyor. Bu, uygulamanızda bu alt dizeleri vurgulamak için kullanışlıdır. Çoğu durumda sorgu, açıklama alanının bir alt dizesi olarak görünür.
  • length, alt dizenin uzunluğudur.
  • offset, eşleşen alt dizenin göründüğü, açıklama dizesinin başı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ı bir Yer Ayrıntıları isteğinin placeId alanına iletin. Bir yere yer kimliğiyle nasıl referans vereceğiniz 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 dizesinin başından itibaren ölçülen karakter ofsetidir.
  • Eşleşen terim: value.

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

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

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

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

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

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

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

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

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

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

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

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

window.initService = initService;
index.js

style.css

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

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

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

Örneği görüntüleyin

Oturum jetonları

AutocompleteService.getPlacePredictions(), faturalandırma amacıyla otomatik tamamlama isteklerini gruplandırmak için oturum jetonlarını (uygulanmışsa) kullanabilir. Oturum jetonları, faturalandırma amacıyla bir kullanıcının otomatik tamamlama aramasının sorgu ve seçim aşamalarını 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. Oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, oturum jetonu sağlanmamış gibi ücretlendirilir (her istek ayrı olarak faturalandırılır).

AutocompleteService.getPlacePredictions() çağrısından elde edilen yerle ilgili tek bir Yer Ayrıntıları isteği göndermek için aynı oturum jetonunu kullanmanız gerekir. 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. İstek için oturum jetonu kullanılmazsa hem otomatik tamamlama isteği hem de Yer Ayrıntıları isteği için ücret alınır.

Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonun birden fazla Otomatik Tamamlama oturumu için 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 nasıl oluşturulduğu ve ardından AutocompleteService içine nasıl aktarıldığı gösterilmektedir (displaySuggestions() işlevi, kısa olması için çıkarılmıştır):

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

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

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

Oturum jetonları hakkında daha fazla bilgi edinin.

Autocomplete ve SearchBox widget'larını stillendirme

Varsayılan olarak, Autocomplete ve SearchBox tarafından sağlanan kullanıcı arayüzü öğeleri, Google Haritalar'a dahil edilmek üzere tasarlanmıştır. Stili kendi sitenize uyacak şekilde ayarlamak isteyebilirsiniz. Aşağıdaki CSS sınıfları kullanılabilir. Aşağıda listelenen tüm sınıflar hem Autocomplete hem de SearchBox widget'ları için geçerlidir.

Yer Adı Otomatik Tamamlama (Eski) optimizasyonu

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

Genel kurallardan bazıları şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Yer Adı Otomatik Tamamlama (Eski) widget'ını, Android için Yerler SDK'sı Yer Adı Otomatik Tamamlama (Eski) widget'ını veya iOS için Yerler SDK'sı Yer Adı Otomatik Tamamlama (Eski) kullanıcı arayüzü kontrolünü kullanmaktır.
• Yer Adı Otomatik Tamamlama (Eski) veri alanlarını en baştan anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
• API bir hata döndürürse uygulamanızın düzgün bir şekilde çalışmaya devam etmesi için hata işleme özelliğini kullanın.
• Uygulamanızın, seçim yapılmadığında bu durumu ele aldığından ve kullanıcılara devam etme yolu sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

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

Gelişmiş maliyet optimizasyonu

SKU: Otomatik Tamamlama - İstek Başına fiyatlandırmaya erişmek ve Yer Ayrıntıları (Eski) yerine seçilen yerle ilgili Geocoding API sonuçlarını istemek için Yer Adı Otomatik Tamamlama'nın (Eski) programatik uygulamasını kullanabilirsiniz. Geocoding API ile eşlenen istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılandığında oturum başına (oturum tabanlı) fiyatlandırmadan daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlem ve boylamına veya adresine ihtiyacınız varsa Geocoding API, bu bilgileri Place Details (Legacy) çağrısından daha düşük bir ücret karşılığında sağlar.
• Kullanıcılar ortalama dört veya daha az Yer Adı Otomatik Tamamlama (Eski) tahmini isteği içinde bir otomatik tamamlama tahmini seçerse istek başına fiyatlandırma, oturum başına fiyatlandırmadan daha uygun maliyetli olabilir.

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

Performansla ilgili en iyi uygulamalar

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

• Place Autocomplete (Legacy) uygulamanıza ülke kısıtlamaları, konum ağırlığı ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar, dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından aldığı için widget'larda dil tercihine gerek yoktur.
• Yer Adı Otomatik Tamamlama (Eski) özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcı, Yer Adı Otomatik Tamamlama (eski) tahminlerinden birini seçmediğinde (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) daha alakalı sonuçlar elde etmek amacıyla orijinal kullanıcı girişini yeniden kullanabilirsiniz:
  • Kullanıcının yalnızca adres bilgisi 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 adresle sorgu girmesini bekliyorsanız Yer Ayrıntıları (Eski) isteği kullanın. Sonuçların yalnızca belirli bir bölgede gösterilmesi bekleniyorsa konum ağırlığı kullanın.
  Geocoding API'ye başvurmanın en iyi seçenek olduğu diğer senaryolar şunlardır:
  • Kullanıcılar, bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini giriyor. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Yer Adı Otomatik Tamamlama (Eski) hizmetinde kısmi bir tahmin döndürür.
  • Kullanıcılar, New York'ta "23-30 29th St, Queens" veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresler giriyor.

Konuma göre yönlendirme

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana göre önceliklendirin. Bu, Yer Adı Otomatik Tamamlama'ya (Eski) tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini söyler. Tanımlanan alanın dışındaki sonuçlar gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülkedeki yerleri gösterecek şekilde filtrelemek için includedRegionCodes parametresini kullanabilirsiniz.

Konum kısıtlama

locationRestriction parametresini ileterek sonuçları belirli bir alanla kısıtlayın.

Ayrıca, strictbounds parametresini ekleyerek sonuçları location ve radius parametresiyle tanımlanan bölgeyle kısıtlayabilirsiniz. Bu, Yer Adı Otomatik Tamamlama'ya (Eski) yalnızca bu bölgedeki sonuçları döndürmesi talimatını verir.

Kullanım sınırları

Kotalar

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