Bu sayfa, Cloud Translation API ile çevrilmiştir.

Yer Arama Öğesi ve Maps JavaScript API ile Yerler'i Keşfetme

Hedef

Kullanıcıların yakındaki yerleri arama veya metin araması yaparak yer bulmasına yardımcı olmak ve ilgi çekici yerleri keşfetme becerilerini geliştirmek için Yer Arama Öğesi'ni Google Haritalar ile nasıl entegre edeceğinizi öğrenin. Uygulamanızda gösterilen yerler hakkında daha fazla ayrıntı sağlamak için Yer Ayrıntıları Kompakt Öğesi'ni kullanın.

Yer Arama Öğesi nedir?

Yer Arama Öğesi, Maps JavaScript API'deki Places UI Kit'in bir parçasıdır. Bu, bir yer aramasının sonuçlarını doğrudan uygulamanızdaki liste biçiminde oluşturmaya yarayan bir HTML öğesidir. Bu öğe, Yakınımda Arama veya Metin Arama kullanılarak bulunan yerleri gösterme sürecini basitleştirerek yer keşfi için sorunsuz bir kullanıcı deneyimi sağlar. Kullanıcı listeden bir yer seçtiğinde, genellikle bir bilgi penceresi ve yer ayrıntıları öğesini kullanarak yerin ayrıntılarını haritada gösterebilirsiniz.

Yer keşfini görselleştirme

Aşağıdaki resimde, Yer Arama Öğesi'nin işleyiş şekliyle ilgili bir örnek verilmiştir. Sol tarafta restoranların listesi (Yer Arama Öğesi) gösterilir. Bir restoran seçildiğinde ayrıntıları haritadaki bilgi penceresinde gösterilir ve harita, restoranın konumuna göre ortalanır.

Yer Keşfi'nin Kullanım Alanları

Yer Arama Öğesi'nin entegrasyonu, farklı sektörlerdeki çeşitli uygulamaları geliştirebilir:

Seyahat ve Turizm: Turistlerin bir bölgedeki ilgi çekici yerleri, otelleri veya belirli yemek türlerini aramasına olanak tanıyın.
Emlak: Potansiyel alıcıların veya kiracıların yakındaki okulları, süpermarketleri ya da toplu taşıma seçeneklerini bulmasına olanak tanıyın.
Lojistik ve Hizmetler: Sürücülerin elektrikli araç şarj istasyonlarını, benzin istasyonlarını veya belirli servis merkezlerini bulmasına yardımcı olun.

Çözüm İş Akışı: Yer Keşfi'ni Uygulama

Bu bölümde, Haritalar'da yer keşfetmek için Yer Arama Öğesi'ni entegre etme adımları ve Places UI Kit ile etkileşimde bulunmaya yönelik kod snippet'leri açıklanmaktadır. Haritayı başlatma ve hem Yakındaki Arama hem de Metin Arama işlevlerini uygulama konularını ele alacağız. Son olarak, haritadaki işaretçisi tıklandığında belirli bir yer hakkında daha fazla ayrıntı göstermek için PlaceDetails öğesini kullanacağız.

Ön koşullar

Aşağıdaki belgeler hakkında bilgi sahibi olmanız önerilir:

Yer Arama Öğesi - Yakında Arama veya Metin Arama kullanılarak yerleri göstermek için kullanılır.
Yer Ayrıntıları Öğesi - Belirli bir yerin ayrıntılarını göstermek için kullanılır.
Maps JavaScript API: Sayfanızda harita göstermek ve Places UI Kit'i içe aktarmak için kullanılır.

Projenizde Maps JavaScript API ve Places UI Kit'i etkinleştirin.

Başlamadan önce Maps JavaScript API'yi yüklediğinizi ve gerekli kitaplıkları içe aktardığınızı doğrulayın. Bu belgede, HTML, CSS ve JavaScript dahil olmak üzere web geliştirme hakkında bilgi sahibi olduğunuz varsayılır.

Sayfaya harita ekleme

İlk adım, sayfanıza harita eklemektir. Bu harita, yer arama öğesi sonuçlarını seçilebilir raptiyeler olarak göstermek için kullanılır.

Sayfaya harita eklemenin iki yolu vardır:

gmp-map HTML web bileşeni kullanma.
JavaScript kullanıyorsanız.

Bu sayfadaki kod snippet'leri, JavaScript haritası kullanılarak oluşturulmuştur.

Harita, kullanıcının arama yapmasını istediğiniz bir konumun (ör. otel) etrafında ortalanabilir veya haritayı ortalamak için kullanıcının mevcut konumunu soracak şekilde başlatılabilir. Bu belgenin amaçları doğrultusunda, aramayı sabitlemek için sabit bir konum kullanacağız.

Sabit bir konumun (ör. otel) yakınındaki yerleri görselleştiriyorsanız bu yeri temsil etmek için haritaya bir işaretçi yerleştirin. Örneğin:

Harita, San Francisco'nun merkezinde yer alıyor ve yakında arama yaptığımız yeri temsil eden mavi bir raptiye gösteriliyor. Raptiye rengi, PinElement kullanılarak özelleştirildi. Harita Türü kontrolü, kullanıcı arayüzünden gizlendi.

Yer Arama Öğesi'ni ayarlama

Şimdi, Yer Arama Öğesi'ni gösterecek HTML ve CSS'yi ayarlayabiliriz. Bu örnekte, öğeyi haritanın sol tarafında kaydıracağız ancak uygulamanıza uygun farklı düzenler denemeniz önerilir.

Yer Arama Öğesi, bildirimsel bir yaklaşım kullanır. Tamamen JavaScript'te yapılandırmak yerine, <gmp-place-nearby-search-request> gibi bir istek öğesini ana <gmp-place-search> bileşeninin içine yerleştirerek arama türünü doğrudan HTML'nizde tanımlarsınız.

HTML kodunuzda bir <gmp-place-search> öğesi başlatın. Sonuçlarda tıklama etkinliklerini etkinleştirmek için selectable özelliğini kullanın. Bu öğenin yakındaki cihazları arama için kullanılacağını belirtmek üzere içine bir <gmp-place-nearby-search-request> ekleyin.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

İlk aramayı yapmak ve sonuçları göstermek için JavaScript'i kullanarak iç içe yerleştirilmiş istek öğesine referans alıp özelliklerini ayarlayacağız. Önceki adımdaki işaretçi konumunu merkez noktası olarak kullanarak locationRestriction olarak kullanılacak bir daire başlatın. Ardından, aramayı tetiklemek için istek öğesinde locationRestriction ve includedPrimaryTypes özelliklerini ayarlayın.

Bunun için kod snippet'i aşağıdaki gibidir:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

Uygulamanın bu aşamada nasıl görünebileceğine dair bir örneği aşağıda bulabilirsiniz:

Kullanıcının arama yapmasına izin ver

Yer Arama Öğesi iki arama seçeneğine izin verir:

<gmp-place-nearby-search-request> - Yer Türleri'ni kullanarak Yakındaki Yerler Arama'dan arama sonuçları oluşturun.
<gmp-place-text-search-request> - "San Francisco'da suşi" gibi serbest metin girişi kullanarak Yerler Metin Arama'dan arama sonuçları oluşturun.

Bunlar, <gmp-place-search> içindeki iç içe yerleştirilmiş öğelerdir. Daha sonra, JavaScript kullanarak bu iç içe yerleştirilmiş istek öğesinde özellikler ayarlayarak aramaları tetiklersiniz.

Bu bölümde, her iki yöntemin de nasıl uygulanacağı açıklanmaktadır.

Yakında arama

Kullanıcıların yakındaki yerleri aramasına izin vermek için öncelikle Yer Türü seçebilecekleri bir kullanıcı arayüzü öğesine ihtiyacınız vardır. Uygulamanız için en uygun seçim yöntemini belirleyin. Örneğin, yer türü seçenekleriyle doldurulmuş bir açılır liste.

Kullanım alanınızla alakalı türlerin bir alt kümesini seçmeniz önerilir. Örneğin, turistlere bir otelin yakınında neler olduğunu gösteren bir uygulama geliştiriyorsanız şunları seçebilirsiniz: bakery, coffee_shop, museum, restaurant ve tourist_attraction.

HTML'niz, içine <gmp-place-nearby-search-request> öğesi yerleştirilmiş bir <gmp-place-search> öğesi içermelidir.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Ardından, yer türü seçicinizde change etkinliği için bir JavaScript dinleyicisi oluşturun. Bu dinleyici, <gmp-place-nearby-search-request> öğesinin özelliklerini güncelleyen bir işlevi çağırır. Bu işlev, otomatik olarak yeni bir arama başlatır ve listeyi günceller.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

Kurulum adımındaki aynı searchCircle, locationRestriction için kullanılır. includedPrimaryTypes özelliği, kullanıcının seçiminden alınan değere ayarlanır. Sonuç sayısını sınırlamak için isteğe bağlı bir maxResultCount de ayarlanır.

Metin arayın

Metin arama özelliğini etkinleştirmek için HTML yapılandırmanızın değiştirilmesi gerekir. Yakındaki arama isteği yerine bir <gmp-place-text-search-request> öğesi yerleştirirsiniz.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

Kullanıcı arayüzünüze bir metin girişi ve arama düğmesi ekleyin. Düğmenin click etkinliği için bir JavaScript dinleyicisi oluşturun. Etkinlik işleyici, kullanıcının girişini alır ve aramayı gerçekleştirmek için <gmp-place-text-search-request> öğesinin özelliklerini günceller.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

Burada, textQuery özelliğini kullanıcının girişiyle ayarlıyoruz. Ayrıca, API'ye sonuçları kesin olarak sınırlamadan bu alan içinde tercih etmesini söyleyen, mevcut harita sınırlarını kullanan bir locationBias da sağlıyoruz. İsteğe bağlı bir maxResultCount, döndürülen sonuç sayısını sınırlar.

Yer raptiyelerini ve ayrıntılarını gösterme

Artık uygulama, yer araması yapabilir ve öğeyi doldurabilir. Bir sonraki adımda, aşağıdaki işlemleri yaparak işlevselliğini artıracağız:

Yer Arama Öğesi'nde doldurulan her yer için haritada raptiyeler gösterilir.
Kullanıcının, belirli bir yer hakkında daha fazla ayrıntı göstermek için bir raptiyeyi veya Yer Arama Öğesi'ndeki yeri tıklamasına izin verme.

Uygulamanın yakındaki arama veya metin araması kullanması bu adımın ilkesini değiştirmez.

Öncelikle yer işaretlerini saklamak için JavaScript kodunuza genel bir değişken ekleyin. Bu sayede, arama değiştiğinde bunları kaldırabilir ve tıklama etkinliklerini işleyebilirsiniz.

let markers = {};

Haritaya işaretçi eklemek için bir işlev oluşturun. Bu işlev, yeni arama sonuçları yüklendiğinde çağrılır. Bu işlem:

Haritadaki mevcut yer işaretlerini kaldırın.
Yer Arama Öğesi'nin sonuçlarını döngüye alın ve her biri için bir işaretçi ekleyin.
Tüm yeni işaretçilerin görünmesi için haritanın sınırlarını ayarlayın.

Arama sonuçlarının ne zaman kullanıma sunulduğunu dinlemek için gmp-load öğesine bir <gmp-place-search> etkinlik dinleyicisi ekleyin. Bu etkinlik, arama tamamlandıktan ve sonuçlar oluşturulduktan sonra tetiklenir.

İşleyiciyi arama işlevimizin içine ekleyeceğiz (ör. updatePlaceList) ve { once: true } seçeneğini kullanarak yalnızca mevcut aramanın sonuçları için tetiklendiğinden emin olun.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

addMarkers işlevi şu şekilde görünür:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

Bu adım tamamlandıktan sonra uygulama, Yer Arama Öğesi tarafından döndürülen her yer için işaretçi gösterme özelliğiyle birlikte aşağıdaki gibi görünür:

Haritada işaretçiler olduğuna göre son adım, Yer Ayrıntıları Öğesi tarafından sağlanan yer ayrıntılarını içeren bir bilgi penceresi göstermek için işaretçi ve öğe tıklama etkinliklerini işlemektir. Bu örnekte Yer Ayrıntıları Kompakt Öğesi'ni kullanacağız.

Kodunuza Yer Ayrıntıları Compact Element HTML'sini ekleyin. Örneğin:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

style, display: none olarak ayarlanmıştır ve gerekli olana kadar görünmez. Tüm öğe içeriğini oluşturmak için gmp-place-all-content iletilir. Hangi içeriğin oluşturulacağını seçmek için Yer Ayrıntıları Kompakt Öğesi dokümanına bakın.

Yer Ayrıntıları Compact Element'e referans tutmak için JavaScript'te global bir değişken oluşturun ve bunu başlatma kodunuzda doldurun. Örneğin:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

addMarkers işlevinde, her işaretçiye bir gmp-click etkinlik işleyicisi ekleyin ve mevcut işaretçinin yer kimliğini ileterek Yer Ayrıntıları Kompakt Öğesi'ni yer ayrıntılarını gösterecek şekilde yapılandırın.

Bu işlem tamamlandıktan sonra, işaretçiye sabitlenmiş Yer Ayrıntıları Kompakt Öğesi'ni görüntülemek için bir Bilgi Penceresi açılır.

Son olarak, harita seçilen yerin görünüm alanına göre konumlandırılır ve görünür hale gelir.

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

Kullanıcının, Yer Ayrıntıları Kompakt Öğesi'ni göstermek için Yer Listesi Öğesi'ndeki bir yeri tıklamasını sağlamak amacıyla, configureFromSearchNearbyRequest çağrısından sonra JavaScript koduna aşağıdakileri ekleyin.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

Bu adım tamamlandıktan sonra uygulama, Yer Listesi Öğesi'ni doldurmak için Yakınlardaki Arama veya Metin Arama'yı kullanabilir. Bu işlemin sonuçları haritada raptiyelerle gösterilir. Bir raptiyeyi veya Yer Listesi Öğesi'ndeki bir yeri tıkladığınızda, Yer Ayrıntıları Kompakt Öğesi tarafından sağlanan yer ayrıntılarını içeren bir bilgi penceresi gösterilir.

Uygulama aşağıdaki gibi görünür:

Sonuç

Yer Arama Öğesi, Yer Ayrıntıları Kompakt Öğesi ile birlikte Google Haritalar Platformu uygulamalarınıza zengin yer keşfi özellikleri eklemenin kolay bir yolunu sunar.

Kullanıcılarınızın hem yakındaki yerleri hem de metin aramalarını kullanarak yerleri bulup keşfetmesini sağlamak ve zengin yer ayrıntılarını göstermek için Places UI Kit'i bugün deneyin. Böylece, kullanıcılarınızın yer keşfi kullanım alanlarınızla etkileşimini artırabilirsiniz.

Katkıda bulunanlar

Henrik Valve | DevX Engineer