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 kodlarını çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken sorgu göndererek anında yer tahminleri sağlayabilir. Places API tarafından tanımlandığı üzere, "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. Şuraya gidin: Google Cloud Console.
  2. Proje seçin düğmesini tıklayın, ardından oluşturduğunuz projeyi seçin JavaScript API'sini açın ve Aç'ı tıklayın.
  3. Kontrol panelindeki API listesinde Places API'yi bulun.
  4. Listede API'yi görüyorsanız hazırsınız demektir. API listede yoksa şunu etkinleştirebilirsiniz:
    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'ı seçin.
    2. Places API'yi arayın ve sonuç listesi.
    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

Rehber hizmeti, ana kütüphaneden ayrı ve bağımsız bir kitaplıktır. Maps JavaScript API kodu. Sunulan işlevleri kullanmak için bu kitaplıkta, önce libraries kullanarak yüklemeniz gerekir parametresi için:

<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

Bu API, aşağıdakileri kullanarak ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar: Autocomplete ve SearchBox sınıfları. 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ılabilir sınıfların özeti aşağıda verilmiştir:

  • Autocomplete, web sayfanıza bir metin giriş alanı ekler ve bu alandaki 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, bilgiler otomatik tamamlama nesnesine döndürülür ve bu öğe tarafından gerçekleştirilir. 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: Metin alanını otomatik tamamlama ve seçim listesi
    Doldurulmuş bir adres formu.
    Şekil 2: Doldurulmuş adres formu
  • SearchBox, web sayfanıza çok daha fazla Autocomplete ile aynıdır. 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çerebilecek genişletilmiş bir tahmin listesi sağlar. Örneğin, kullanıcı yazarsa, seçim listesi şu ifadeyi içerebilir: "kebap in İstanbul" çeşitli pizzaların adlarını da priz.
    • SearchBox, aramayı kısıtlamak için Autocomplete'e kıyasla daha az seçenek sunar. Birincisinde, aramayı belirli bir LatLngBounds'ye yönlendirebilirsiniz. arama özelliğini kullanırken, aramayı sadece bir ülke için geçerli yer türlerini öğrenmek ve sınırları belirlemek gibi. Daha fazla bilgi için bkz. burada bulabilirsiniz.
    Adres formu dolduruldu.
    Şekil 3: Arama kutusu, arama terimlerini ve yer tahminlerini sunar.
    Ayrıntıları aşağıda bulabilirsiniz.
  • Tahminleri programatik olarak almak için bir AutocompleteService nesnesi oluşturabilirsiniz. getPlacePredictions() numaralı telefonu arayın: eşleşen yerleri alın veya getQueryPredictions() numaralı telefonu arayın eşleşen yerleri ve önerilen arama terimlerini öğren. Not: AutocompleteService, kullanıcı arayüzü denetimi eklemez. Bunun yerine, yukarıdaki yöntemler bir dizi tahmin nesnesi döndürür. Her biri tahmin nesnesi, tahmin metnini ve referans metnini içeren sonucun kullanıcı girişiyle nasıl eşleştiğine dair bilgi ve ayrıntılar. Bkz. aşağıda görebilirsiniz.

Otomatik Tamamlama widget'ı ekleme

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

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

  • text türünde bir HTML input öğesi. Bu, otomatik tamamlamanın düzenlediği giriş alanıdır hizmetin, izlemesi ve eklemesi gereken ek bilgilerdir.
  • 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 bölümüne bakın.
    • 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, yer aranacak alanı belirten bir google.maps.LatLngBounds nesnesi. Sonuçlar tarafsız olsa da yalnızca aşağıdakilerle sınırlı değildir: yer alır.
    • 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. Aşağıdakiler olsa bile API, bu bölgenin dışında sonuç döndürmez: kullanıcı girişiyle eşleşir.
    • componentRestrictions, sonuçları şununla kısıtlamak için kullanılabilir: yararlanabilirsiniz. Ş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. Arama yapılıyor Autocomplete nesnesinde getPlace(), PlaceResult kullanılabilir hale gelende yalnızca place id bulunur, types ve name özellikleri ayarlandı. 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, Otomatik Yer Tamamlama özelliği, kullanıcının konumunu belirler ve kullanıcının seçtiği yere ilişkin tüm veri alanlarını getirir. Kullanım alanınıza göre daha alakalı tahminler sunmak için yer otomatik tamamlama seçeneklerini ayarlayın.

İnşaat aşamasında seçenekleri ayarlama

Autocomplete oluşturucu bir AutocompleteOptions kabul ediyor parametresini kullanabilirsiniz. Aşağıdaki örnek, bounds, componentRestrictions ve types seçeneklerini belirtilen coğrafi bölgedekilere tercih ederek establishment türü yerler iste ve tahminleri yalnızca Amerika Birleşik Devletleri'ndeki yerlerle sınırlandırıyoruz. 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'ta bir seçeneğin değerini değiştirmek için setOptions() komutunu ç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ı belirtin

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

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

Her bir ekip için sapmaları ve arama alanı sınırlarını Otomatik tamamlama

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 ile ilgili sınırları değiştirin.
  • Haritanın görüntü alanı için sınırları belirleyin.
  • Aramayı sınırlarla kısıtlayın.
  • Aramayı belirli bir ülkeyle sınırlandırın.

Önceki örnekte, oluşturulurken sınırların nasıl ayarlanacağı 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'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ından bağlantısını kaldırmak için unbind() öğesini 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 inceleyin

Aramayı mevcut sınırlarla kısıtlama

Sonuçları, harita görünümüne veya dikdörtgen sınırlara dayalı olarak geçerli sınırlarla sınırlamak 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ş ülke içeren belirli bir ülke grubuyla 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 bir tür veya tür koleksiyonunu belirtir Yer Türleri'nde belirtildiği şekilde seçin. 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']);
  • Tablo 3'teki herhangi bir filtre Yer Türleri arasından seçim yapın. 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 tamamlamaya ekli tahminlerden bir yer seçtiğinde metin alanına sahipse hizmet, bir place_changed etkinliğini 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.getPlace() numaralı telefonu arayın PlaceResult almak için Autocomplete nesnesinde Böylece, seçtiğiniz nesne hakkında daha fazla bilgi edinmek için yer.

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. Autocomplete.setFields() kullanın döndürülecek yer verisi alanlarını belirtin. İsteyebilirsiniz yer verisi alanlarının listesi dahil olmak üzere PlaceResult nesnesi hakkında daha fazla bilgi edinin. İhtiyacınız olmayan veriler için ödeme yapmamak istiyorsanız Autocomplete.setFields() kullanarak yalnızca kullanacağınız yer verilerini ekleyin.

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ı için adresin yapılandırılmış biçimde alınması yararlıdır. Alıcı: seçilen yerin yapılandırılmış adresini döndürün, Autocomplete.setFields() ve address_components alanını belirtin.

Aşağıdaki örnekte, adres formunda 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();
}
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

Varsayılan olarak, otomatik tamamlama hizmeti tarafından oluşturulan metin alanında standart yer tutucu metni. Metni değiştirmek için input öğesindeki placeholder özelliği:

<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 görünümünü özelleştirmek için Otomatik tamamlama ve Arama Kutusu widget'larının stilini belirleme başlıklı makaleye bakın.

SearchBox, kullanıcıların metin tabanlı bir coğrafi konum gerçekleştirmesine olanak tanır. "İstanbul'da pizza" gibi bir arama yapın veya "robson sokağı yakınındaki ayakkabı mağazaları" gibi aramalar yapabilirsiniz. SearchBox öğesini bir metin alanına ekleyebilir ve metin girildiğinde hizmet, açılır liste biçimindedir.

SearchBox, tahminlerin daha kapsamlı bir listesini sunar. yerleri (Yerler API'si tarafından tanımlandığı şekliyle) ve önerilen aramayı içerebilir şartlarını kabul edersiniz. Ö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 yer hakkındaki bilgiler Arama Kutusu nesnesine döndürülür ve uygulamanız tarafından alındı.

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

  • text türündeki bir HTML input öğesi. Bu SearchBox hizmetinin izleyeceği giriş alanını ekleyebilirsiniz.
  • Şunları içerebilecek bir options bağımsız değişkeni bounds mülkü: bounds bir google.maps.LatLngBounds yerlerin aranacağı alanı belirten bir nesnedir. 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
});

Arama Kutusu 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ı aramaya ekli tahminlerden bir öğe seçtiğinde kutusunda, hizmet bir places_changed etkinliği tetikler. Şunları yapabilirsiniz: SearchBox nesnesinde getPlaces() yöntemini çağırın Her biri bir tahmin içeren ve her biri PlaceResult nesne.

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 görünümünü özelleştirmek için Otomatik tamamlama ve Arama Kutusu widget'larının stilini belirleme başlıklı makaleye bakın.

Otomatik Yer Tamamlama Hizmeti tahminlerini programatik olarak alma

Tahminleri programatik olarak almak için AutocompleteService sınıfı. AutocompleteService. herhangi bir kullanıcı arayüzü denetimi eklemez. Bunun yerine bir tahmin dizisi döndürüyor her biri tahmin metnini, referans bilgilerini ve bilgileri içeren ve sonucun kullanıcı girişiyle nasıl eşleştiğine dair ayrıntılar. Bu özellik, kullanıcı arayüzü üzerinde Autocomplete ve SearchBox tarafından sunulmaktadır 'ne başvurun.

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

  • 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(), şunun genişletilmiş bir listesini döndürür: yerleri içerebilen tahminler (Place API tarafından tanımlandığı şekliyle) artı önerilen arama terimleri. Ö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 her ikisi de tahmin nesnelerinde bulunacaktır:

  • description, eşleşen tahmindir.
  • distance_meters, belirtilen AutocompletionRequest.origin'a olan mesafeyi (metre cinsinden) gösterir.
  • matched_substrings, kullanıcının girişindeki öğelerle eşleşen açıklama. 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, karakter uzaklığıdır ve açıklama dizesinin başlangıcı, burada eşleşen alt dize görünür.
  • 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, sorgu öğelerini içeren bir dizidir. Örneğin, yer alırsa 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 örnek, şu ifade için bir sorgu tahmin isteği yürütür: "yakınımda pizzacı" ve sonucu bir listede görüntüler.

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 inceleyin

Oturum jetonları

AutocompleteService.getPlacePredictions() Faturalandırma için otomatik tamamlama isteklerini birlikte gruplandırmak üzere oturum jetonlarını (uygulandıysa) kullanabilir amaçlar. 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. Oturum sona erdiğinde jeton artık geçerli olmaz. Uygulamanız her oturum için yeni bir jeton oluşturmalıdır. Şunun için oturum jetonları kullanmanızı öneririz: tüm otomatik tamamlama oturumlarını kullanabilirsiniz. sessionToken parametresi atlanırsa veya bir oturum jetonunu yeniden kullanırsanız oturum, oturum jetonu sağlandı (her istek ayrı olarak faturalandırılır).

Aynı oturum jetonunu kullanarak tek bir Yer Ayrıntıları AutocompleteService.getPlacePredictions() numaralı telefona yapılan aramadan kaynaklanan yerle ilgili istek. Bu durumda, otomatik tamamlama isteği Yer Ayrıntıları ile birleştirilir isteği yer alır ve arama, normal Yer Ayrıntısı isteği olarak ücretlendirilir. Ücretsiz Otomatik tamamlama isteği.

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 jetonu oluşturma ve daha sonra bunu AutocompleteService (displaySuggestions() fonksiyonunun kısaltılması için atılmıştır):

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

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

Her yeni oturum için benzersiz bir oturum jetonu ilettiğinizden emin olun. Aynı jetonun birden fazla oturumda kullanılması, her isteğ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 bir Google haritasına dahil edilmek üzere stilize edildi. 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 ve SearchBox widget'ları.

Otomatik tamamlama ve otomatik tamamlama için CSS sınıflarının Arama Kutusu widget&#39;ları
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 Tahminler listesinde her öğenin solunda gösterilen simge.
pac-item Autocomplete veya SearchBox widget'ı.
pac-item:hover Kullanıcı fare imlecini üzerine getirdiğinde öğe.
pac-item-selected Kullanıcı klavyeyi kullanarak 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 Çalışmanın ana parçası olan bir pac-item içindeki bir tahmindir. Coğrafi konumlar için bu alan, "Sydney" gibi bir yer adı veya "10 King Street" gibi bir sokak adı ve numarası içerir. Örneğin, "İstanbul'da pizza" gibi metin tabanlı aramalar, aramanın tam metnini anlamına gelir. 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. Lütfen eşleşen metin pac-item içinde herhangi bir yerde olabilir. değil mutlaka pac-item-query kapsamındadır ve kısmen pac-item-query içinde ve kalan metnin içinde pac-item içinde.

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.

Bazı genel kurallar şunlardır:

  • Ç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 Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü
  • Yer Otomatik Tamamlama'nın 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 bozulmasını sağlamak için hata işleme özelliğini kullanın.
  • Uygulamanızın seçim yapılmadığı durumlarda bunu yaptığından ve kullanıcılara seçeneğini tıklayın.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Yer Tamamlama özelliğini kullanmanın maliyetini optimize etmek için hizmeti kullanmak için, Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larındaki alan maskelerini kullanarak yalnızca yer veri alanlarını 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. Aşağıdaki koşulların her ikisi de karşılanırsa İstek Başına Fiyatlandırma, Geocoding API ile eşleştirilen Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:

  • Yalnızca kullanıcının seçtiği yerin 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ız, seçilen tahminin adresi ve enlem/boylam dışında herhangi bir bilgi gerektiriyor mu?

Evet, daha fazla ayrıntı gerekiyor

Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
. Uygulamanız; yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gerektirdiğinden, Otomatik Yer Tamamlama uygulamanız programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunan bir oturum jetonu kullanmalıdır.Bu kullanım için toplamda 0,017 ABD doları tutarında oturum başına maliyet ve geçerli Yer Verileri SKU'ları kullanılabilir.

Widget uygulaması
Oturum yönetimi otomatik olarak JavaScript, Android veya iOS widget'larına eklenir. Buna hem otomatik Yer Tamamlama istekleri hem de seçilen tahmindeki Yer Ayrıntısı isteği dahildir. 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 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. fields parametresi, İhtiyacınız olan yer verisi alanlarını

Hayır, yalnızca adres ve konum bilgisi gerekir.

Yerler 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, hangi kullanıcıların giriş yaptığına, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaları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 Yer Otomatik Tamamlama tahmini seçmeden önce ortalama 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çili 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 adet Otomatik Otomatik Tamamlama - İstek Başına isteği göndermenin maliyeti 0,01132 ABD dolarıdır. Dolayısıyla, seçilen yer tahminiyle ilgili dört isteğin toplam maliyeti ile birlikte Coğrafi Kodlama API'si çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu da oturum başına 0,017 ABD doları olan Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.1

Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performans en iyi uygulamalarından yararlanmayı düşünebilirsiniz.

Hayır

Yer Ayrıntıları ile oturum tabanlı yer otomatik tamamlamayı kullanın.
. Bir kullanıcı Otomatik Yer Tamamlama tahminini seçmeden önce gerçekleştirmeyi beklediğiniz ortalama istek sayısı Oturum Başına fiyatlandırmayı aştığından, Otomatik Yer Tamamlama özelliğini uygulamanız hem Otomatik Yer Tamamlama istekleri hem de bununla ilişkili Yer Ayrıntısı isteği için bir oturum jetonu kullanarak toplam oturum başına 0,017 ABD doları tutarında maliyet içermelidir.1

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

Programatik uygulama
Otomatik Yer Tamamlama isteklerinizde bir 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 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 Otomatik Tamamlama uygulama kılavuzunu takip edebilirsiniz. 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 kısa sürede elde etmelerine yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

  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:

  • Ülke kısıtlamaları ekleyin, konuma ağırlık verme, Otomatik Yer Tamamlama ayarınıza (programatik uygulamalar için) dil tercihinizi ekleyin hakkında bilgi edindiniz. Dil tercihi yapmanız gerekmez Dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından seçtikleri için, widget'larla
  • Yer Otomatik Tamamlama özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre kaydırabilirsiniz.
  • 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 ada veya adrese göre belirli bir yer hakkında sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık verme.
    Coğrafi Kodlama API'sini kullanmanın en iyi seçenek olacağı diğer senaryolar şunlardır:
    • Otomatik Yer Tamamlama desteğinin sunulduğu ülkelerdeki alt şirket içi adresleri giren kullanıcılar alt şirket adresleri eksik, ör. Çekya, Estonya ve Litvanya. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha" Place’de kısmi bir tahmin verir Otomatik tamamlama.
    • "23-30 29th St, Queens" gibi yol ön ekleriyle adresler giren kullanıcılar bir listesini oluştur: New York City veya "47-380 Kamehameha Hwy, Kaneohe" bir şehir parkı var.

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.