Yeni Yer Adı Otomatik Tamamlama'ya geçiş

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Fatura adresiniz Avrupa Ekonomik Alanı'ndaysa 8 Temmuz 2025'ten itibaren Hizmetler'i kullanımınız Google Haritalar Platformu AEA Hizmet Şartları'na tabi olacaktır. İşlevler bölgeye göre değişir. Daha fazla bilgi edinin.

Yer Adı Otomatik Tamamlama, Maps JavaScript API'deki Places kitaplığının bir özelliğidir. Uygulamalarınıza Google Haritalar arama alanının yazarken arama davranışını kazandırmak için otomatik tamamlama özelliğini kullanabilirsiniz.

Bu sayfada, eski ve yeni Yer Adı Otomatik Tamamlama özellikleri arasındaki farklar açıklanmaktadır. Her iki sürümde de otomatik tamamlama özelliğini entegre etmenin iki genel yolu vardır:

• Programatik arayüz: Otomatik tamamlama deneyimi üzerinde daha fazla özelleştirme ve kontrol isteyen geliştiriciler için.
• Yer Adı Otomatik Tamamlama widget'ı: Haritaya veya web sayfasına yerleştirilebilen bir arama çubuğudur.

Otomatik tamamlama programatik arayüzü

Aşağıdaki tabloda, Places Autocomplete Service (eski) ile Autocomplete Data API (yeni) arasında programatik Yer Adı Otomatik Tamamlama kullanımındaki bazı temel farklılıklar listelenmiştir:

PlacesService (Eski)	Place (Yeni)
Yer Adı Otomatik Tamamlama Hizmeti referansı	Autocomplete Data (new) referansı
AutocompletionRequest	AutocompleteRequest
AutocompleteService.getPlacePredictions	AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction	PlacePrediction
Yöntemler, sonuç nesnesini ve PlacesServiceStatus yanıtını işlemek için bir geri çağırma işlevinin kullanılmasını gerektirir.	Promises kullanır ve eşzamansız olarak çalışır.
Yöntemler için PlacesServiceStatus kontrolü gerekir.	Durum kontrolü gerekmez, standart hata işleme kullanılabilir. Daha fazla bilgi
Yer verisi alanları, örnek oluşturulurken seçenek olarak Autocomplete ayarlanır.	Yer verisi alanları daha sonra fetchFields() çağrıldığında ayarlanır.
Sorgu tahminleri desteklenir (yalnızca SearchBox).	Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
Sabit bir yer türleri ve yer verisi alanları kümesiyle sınırlıdır.	Daha geniş bir yer türü ve yer verisi alanı seçeneğine erişim.

Aşağıdakiler hem eski hem de yeni Autocomplete API'leri tarafından kullanılır:

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

Kod karşılaştırması (programatik)

Bu bölümde, programatik arayüzler için Places Service ile Place sınıfı arasındaki farkları göstermek amacıyla otomatik tamamlama kodları karşılaştırılmaktadır.

Otomatik tamamlama tahminlerini alma (eski)

Eski Places Service, Autocomplete sınıfının sunduğundan daha fazla kullanıcı arayüzü kontrolü için otomatik tamamlama tahminlerini programatik olarak almanıza olanak tanır. Aşağıdaki örnekte, "par" için tek bir istekte bulunulur. Bu istekte, giriş değerini ve tahmini yönlendirmek için bir dizi sınırı içeren bir AutocompletionRequest bulunur. Örnek, AutocompletePrediction örneklerinin listesini döndürür ve her birinin açıklamasını gösterir. Örnek işlev ayrıca bir oturum jetonu oluşturur ve bunu isteğe uygular.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    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 placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

• Yer Adı Otomatik Tamamlama Hizmeti tahminlerini programatik olarak alma
• Yer Adı Otomatik Tamamlama örneği
• Oturum jetonları
• AutocompletionRequest reference
• AutocompletePrediction reference

Otomatik tamamlama tahminlerini alma (yeni)

Yeni Place sınıfı, kullanıcı arayüzü üzerinde PlaceAutocompleteElement sınıfının sunduğundan daha fazla kontrol sahibi olmak için otomatik tamamlama tahminlerini programatik olarak almanıza da olanak tanır. Aşağıdaki örnekte, "par" için tek bir istekte bulunulur. Bu istekte, giriş değerinden ve tahmini yönlendirmek için bir dizi sınırdan oluşan bir AutocompleteRequest kullanılır. Örnek, placePrediction örneklerinin listesini döndürür ve her birinin açıklamasını gösterir. Örnek işlev ayrıca bir oturum jetonu oluşturur ve bunu isteğe uygular.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

• Place Autocomplete Data API
• Yer Adı Otomatik Tamamlama Veri Tahminleri örneği
• Yer Adı Otomatik Tamamlama Veri Oturumları örneği
• Oturum jetonları
• AutocompleteRequest arayüz referansı
• AutocompleteSuggestion sınıf referansı
• PlacePrediction sınıf referansı

Yer Adı Otomatik Tamamlama widget'ı

Aşağıdaki tabloda, Places hizmeti (eski) ile Place sınıfı (yeni) arasında otomatik tamamlama widget'larının kullanımıyla ilgili temel farklardan bazıları listelenmiştir:

Places Hizmeti (Eski)	Yer (Yeni)
yer tahminleri için Autocomplete sınıfı.	yer tahminleri için PlaceAutocompleteElement sınıfı.
Sorgu tahminleri için SearchBox sınıfı .	Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
Yalnızca varsayılan giriş yer tutucu metni yerelleştirilir.	Metin girişi yer tutucusu, tahmin listesi logosu ve yer tahminlerinin tümü bölgesel yerelleştirmeyi destekler.
Widget, aramayı belirtilen sınırlarla kısıtlamak (önceliklendirmek) için setBounds() veya autocomplete.bindTo(), sonuçları belirtilen sınırlarla kısıtlamak için ise strictBounds kullanır.	Widget, sonuçları belirtilen sınırlara yönlendirmek için locationBias özelliğini, aramayı belirtilen sınırlarla kısıtlamak için ise locationRestriction özelliğini kullanır.
Widget'lar yalnızca standart bir HTML giriş öğesi kullanılarak entegre edilebilir.	Widget, standart bir HTML giriş öğesi veya gmp-place-autocomplete öğesi kullanılarak entegre edilebilir.
Kullanıcılar widget'ı kullanırken geçerli olmayan şeyler (ör. "bisneyland") isteyebilir. Bu durumun açıkça ele alınması gerekir.	Widget yalnızca sağlanan önerilerle ilgili sonuçları döndürür ve rastgele değerler için istek gönderemez. Bu nedenle, geçersiz olabilecek isteklerin işlenmesine gerek yoktur.
Eski PlaceResult örneğini döndürür.	Place örneğini döndürür.
Yer verileri alanları, Autocomplete nesnesi için seçenek olarak ayarlanır.	Yer verileri alanları, kullanıcı seçim yaptığında ayarlanır ve fetchFields() çağrılır.
Sabit bir yer türleri ve yer verisi alanları kümesiyle sınırlıdır.	Daha geniş bir yer türü ve yer verisi alanı seçeneğine erişim.

Kod karşılaştırması (widget'lar)

Bu bölümde, eski Yer Adı Otomatik Tamamlama widget'ı ile yeni Yer Adı Otomatik Tamamlama öğesi arasındaki farkları göstermek için otomatik tamamlama kodu karşılaştırılmaktadır.

Yer Adı Otomatik Tamamlama Widget'ı (eski)

Places Service, Autocomplete ve SearchBox sınıflarını kullanarak ekleyebileceğiniz iki tür otomatik tamamlama widget'ı sunar. Her widget türü, haritaya harita kontrolü olarak eklenebilir veya doğrudan bir web sayfasına yerleştirilebilir. Aşağıdaki kod örneğinde, harita kontrolü olarak bir Autocomplete widget'ının yerleştirilmesi gösterilmektedir.

• Autocomplete widget 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.
  • Sorguyu kısıtlamak için daha fazla seçenek belirtebileceğiniz isteğe bağlı bir AutocompleteOptions bağımsız değişkeni.
• Sınırları ayarlamak için Autocomplete örneği, autocomplete.bindTo() çağrılarak haritaya açıkça bağlanabilir.
• Otomatik tamamlama seçeneklerinde yer verisi alanlarını belirtin.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

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

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

• Yer Adı Otomatik Tamamlama dokümanları
• Yer Adı Otomatik Tamamlama widget'ı örneği
• Yer Arama Kutusu örneği
• Autocomplete sınıf referansı

Yer Adı Otomatik Tamamlama Widget'ı (Yeni)

Place sınıfı, haritaya harita kontrolü olarak eklenebilen veya doğrudan bir web sayfasına yerleştirilebilen bir kullanıcı arayüzü bileşeni sağlayan HTMLElement alt sınıfı olan PlaceAutocompleteElement'i sunar. Aşağıdaki kod örneğinde, harita kontrolü olarak bir PlaceAutocompleteElement widget'ının yerleştirilmesi gösterilmektedir.

Yer Adı Otomatik Tamamlama widget'ı aşağıdaki şekillerde iyileştirildi:

• Otomatik tamamlama widget'ı kullanıcı arayüzü; metin girişi yer tutucusu, tahmin listesi logosu ve yer tahminleri için bölgesel yerelleştirmeyi (sağdan sola yazılan diller dahil) destekler.
• Ekran okuyucular ve klavye etkileşimi desteği dahil olmak üzere gelişmiş erişilebilirlik.
• Otomatik tamamlama widget'ı, döndürülen nesnenin işlenmesini basitleştirmek için yeni Place sınıfını döndürür.
• Mobil cihazlar ve küçük ekranlar için daha iyi destek.
• Daha iyi performans ve iyileştirilmiş grafik görünümü.

Uygulamadaki temel farklılıklar şunlardır:

• PlaceAutocompleteElement kendi giriş alanını sağlar ve mevcut bir giriş öğesi sağlanmak yerine HTML veya JavaScript kullanılarak doğrudan sayfaya eklenir.
• Sorgu tahminleri Autocomplete sınıfında kullanılamaz.
• PlaceAutocompleteElement, PlaceAutocompleteElementOptions kullanılarak oluşturulur.
  • Yer verisi alanları, seçim sırasında (fetchFields() çağrıldığında) belirtilir.
• locationBounds veya locationRestriction seçeneğini kullanarak sınırları belirleyin.

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  const placeAutocomplete =
    new google.maps.places.PlaceAutocompleteElement({
      locationRestriction: map.getBounds(),
    });

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  // Create the marker and infowindow.
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});

  // Add the gmp-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( event ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "viewport"],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      map.fitBounds(place.viewport);
    } else {
      map.setCenter(place.location);
      map.setZoom(17);
    }

    let content =
      '<div id="infowindow-content">' +
      '<span id="place-displayname" class="title">' +
      place.displayName +
      '</span><br />' +
      '<span id="place-address">' +
      place.formattedAddress +
      '</span>' +
      '</div>';

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}

• Yer Adı Otomatik Tamamlama Bileşeni (Önizleme) dokümanları
• Yer Adı Otomatik Tamamlama widget'ı örneği
• Yer Adı Otomatik Tamamlama öğesi örneği
• PlaceAutocompleteElement sınıf referansı