Yakındaki Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

Yakındaki Arama (Yeni) isteği, daire şeklinde belirtilen ve dairenin merkez noktasının enlem ve boylam koordinatlarıyla ve metre cinsinden yarıçapla tanımlanan arama bölgesini girdi olarak alır. İstek, belirtilen arama alanı içindeki her biri bir Place nesnesiyle temsil edilen eşleşen yerlerin bir listesini döndürür.

Varsayılan olarak yanıt, arama alanı içindeki her türden yeri içerir. İsterseniz yanıta açıkça dahil edilecek veya yanıttan hariç tutulacak yer türlerinin listesini belirterek yanıtı filtreleyebilirsiniz. Örneğin, yanıta yalnızca "restoran", "fırın" ve "kafe" türündeki yerleri dahil etmeyi veya "okul" türündeki tüm yerleri hariç tutmayı belirtebilirsiniz.

Yakındaki Arama (Yeni) istekleri

İstek parametrelerini tanımlayan bir SearchNearbyRequest nesnesi ileterek PlacesClient.searchNearby yöntemini çağırarak Yakındaki Arama (Yeni) isteğinde bulunun.

SearchNearbyRequest nesnesi, istek için gerekli ve isteğe bağlı tüm parametreleri belirtir. Gerekli parametreler şunları içerir:

  • Alan maskesi olarak da bilinen Place nesnesinde döndürülecek alanların listesi. Alan listesinde en az bir alan belirtmezseniz veya alan listesini atlarsanız çağrı bir hata döndürür.
  • Arama alanı için, metre cinsinden bir enlem/boylam çifti ve yarıçap değeri olarak tanımlanan konum kısıtlaması.

Bu örnek yakındaki arama isteği, yanıt Place nesnelerinin, arama sonuçlarındaki her Place nesnesi için Place.Field.ID ve Place.Field.NAME yer alanlarını içerdiğini belirtir. Ayrıca yanıtı yalnızca "restoran" ve "kafe" türündeki yerleri döndürecek ancak "pizza_restoran" ve "american_restoran" türündeki yerleri hariç tutacak şekilde filtreler.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Yakındaki Arama (Yeni) yanıtları

SearchNearbyResponse sınıfı, bir arama isteğinden gelen yanıtı temsil eder. SearchNearbyResponse nesnesi şunları içerir:

  • Eşleşen yer başına bir Place nesnesi olmak üzere, eşleşen tüm yerleri temsil eden Place nesnelerin listesi.
  • Her Place nesnesi yalnızca istekte iletilen alan listesiyle tanımlanan alanları içerir.

Örneğin, istekte bir alan listesini şu şekilde tanımladınız: 

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Bu alan listesi, yanıttaki her Place nesnesinin yalnızca eşleşen her yerin yer kimliğini ve adını içerdiği anlamına gelir. Daha sonra her bir Place nesnesinde bu alanlara erişmek için Place.getId() ve Place.getName() yöntemlerini kullanabilirsiniz.

Bir Place nesnesindeki verilere erişme hakkında daha fazla örnek için Yer nesnesi veri alanlarına erişme konusuna bakın.

Gerekli parametreler

Arama için gerekli parametreleri belirtmek üzere SearchNearbyRequest nesnesini kullanın.

  • Alan listesi

    Yer ayrıntılarını istediğinizde, bu yerin Place nesnesinde döndürülecek verileri alan maskesi olarak belirtmeniz gerekir. Alan maskesini tanımlamak için Place.Field öğesinden SearchNearbyRequest nesnesine bir değer dizisi iletin. Alan maskeleme, gereksiz veri isteğinde bulunmadığınızdan emin olmak için iyi bir tasarım uygulamasıdır ve gereksiz işleme süresi ve faturalandırma ücretlerinin önlenmesine yardımcı olur.

    Aşağıdaki alanlardan birini veya daha fazlasını belirtin:

    • Aşağıdaki alanlar Yakındakilerde Arama (Temel) SKU'sunu tetikler:

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Aşağıdaki alanlar Yakında Arama (Gelişmiş) SKU'sunu tetikler:

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • Aşağıdaki alanlar Yakındakilerde Arama (Tercih Edilen) SKU'sunu tetikler:

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    Alan listesi parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setPlaceFields() yöntemini çağırın.

    Aşağıdaki örnekte, bir istek tarafından döndürülen Place nesnesinin Place.Field.ID ve Place.Field.NAME alanlarını içerdiğini belirtmek için iki alan değerinden oluşan bir liste tanımlanmaktadır:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

  • Konum kısıtlaması

    Daire olarak belirtilen, aranacak bölgeyi tanımlayan, merkez noktası ve metre cinsinden yarıçapla tanımlanan LocationRestriction nesnesi. Yarıçap, 0,0 ile 50000,0 veya daha küçük bir değer arasında olmalıdır. Çok küçük bir yarıçap belirtmenin yanıt olarak ZERO_RESULTS değerini döndüreceğini unutmayın.

    Konum kısıtlaması parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setLocationRestriction() yöntemini çağırın.

İsteğe bağlı parametreler

Arama için isteğe bağlı parametreleri belirtmek üzere SearchNearbyRequest nesnesini kullanın.

  • Türler ve birincil türler

    Arama sonuçlarını filtrelemek için kullanılan Tablo A türlerinden bir tür listesi belirtebilmenizi sağlar. Her bir tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.

    Bir yerin kendisiyle ilişkili tek bir birincil türü olabilir Tablo A. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir. Sonuçları bir yerin birincil türüne göre filtrelemek için includedPrimaryTypes ve excludedPrimaryTypes özelliklerini kullanın.

    Bir yer, kendisiyle ilişkili Tablo A türlerinden birden fazla tür değere sahip olabilir. Örneğin bir restoran şu türlere sahip olabilir: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Bir yerle ilişkili türler listesindeki sonuçları filtrelemek için includedTypes ve excludedTypes özelliklerini kullanın.

    Bir arama birden çok tür kısıtlamasıyla belirtilirse yalnızca tüm kısıtlamaları karşılayan yerler döndürülür. Örneğin, includedTypes = Arrays.asList("restaurant") ve excludedPrimaryTypes = Arrays.asList("steak_house") belirtirseniz döndürülen yerler "restaurant" ile ilgili hizmetler sağlar ancak birincil olarak "steak_house" olarak çalışmaz.

    includedTypes ve excludedTypes kullanımının nasıl kullanılacağına dair bir örnek için Yakında Arama (Yeni) istekleri konusuna bakın.

    Dahil edilen türler

    A tablosunda aranacak yer türlerinin listesi. Bu parametre eklenmezse her türden yer döndürülür.

    Dahil edilen türler parametresini ayarlamak için, SearchNearbyRequest nesnesini oluştururken setIncludedTypes() yöntemini çağırın.

    Hariç tutulan türler

    Aramadan hariç tutulacak A Tablosu'ndaki yer türlerinin listesi.

    İstekte hem includedTypes ("school" gibi) hem de excludedTypes ("primary_school" gibi) değerini belirtirseniz yanıt, "school" olarak sınıflandırılan ancak "primary_school" olarak sınıflandırılmayan yerleri içerir. Yanıt, includedTypes özelliklerinden en az biriyle eşleşen ve excludedTypes hiçbiriyle eşleşen yerleri içerir.

    Çakışan türler varsa (ör. hem includedTypes hem de excludedTypes'da görünen bir tür) INVALID_REQUEST hatası döndürülür.

    Hariç tutulan türler parametresini ayarlamak için, SearchNearbyRequest nesnesini oluştururken setExcludedTypes() yöntemini çağırın.

    Dahil edilen birincil türler

    Aramaya dahil edilecek, A Tablosu'ndan alınan birincil yer türlerinin listesi.

    Dahil edilen birincil türler parametresini ayarlamak için, SearchNearbyRequest nesnesini oluştururken setIncludedPrimaryTypes() yöntemini çağırın.

    Hariç tutulan birincil türler

    Aramadan hariç tutulacak A Tablosu'ndaki birincil yer türlerinin listesi.

    Hem includedPrimaryTypes hem de excludedPrimaryTypes içinde görünen bir tür gibi çakışan birincil türler varsa INVALID_ARGUMENT hatası döndürülür.

    Hariç tutulan birincil türler parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setExcludedPrimaryTypes() yöntemini çağırın.

  • Maksimum sonuç sayısı

    Döndürülecek maksimum yer sonucu sayısını belirtir. 1-20 (varsayılan) dahil bu değerler arasında olmalıdır.

    Maksimum sonuç sayısı parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setMaxResultCount() yöntemini çağırın.

  • Sıralama tercihi

    Kullanılacak sıralama türü. Bu parametre eklenmezse sonuçlar popülerliğe göre sıralanır. Aşağıdakilerden biri olabilir:

    • POPULARITY (varsayılan) Sonuçları popülerliklerine göre sıralar.
    • DISTANCE Sonuçları, belirtilen konuma olan mesafelerine göre artan düzende sıralar.

    Sıralama tercihi parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setRankPreference() yöntemini çağırın.

  • Bölge kodu

    Yanıtı biçimlendirmek için kullanılan bölge kodu. İki karakterli CLDR kodu değeri olarak belirtilir. Varsayılan bir değer yok.

    Yanıttaki formattedAddress alanının ülke adı regionCode ile eşleşirse ülke kodu formattedAddress öğesinden çıkarılır.

    Çoğu CLDR kodu, bazı önemli istisnalar dışında, ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu "gb" (teknik olarak "Büyük Britanya ve Kuzey İrlanda'daki Birleşik Krallık'a" ait tüzel kişi için) "gb" şeklindedir. Parametre, geçerli yasalara göre sonuçları etkileyebilir.

    Bölge kodu parametresini ayarlamak için SearchNearbyRequest nesnesini oluştururken setRegionCode() yöntemini çağırın.

İlişkilendirmeleri uygulamanızda gösterme

Uygulamanız, PlacesClient'ten elde edilen bilgileri (ör. fotoğraflar ve yorumlar) görüntülediğinde gerekli atıfları da göstermelidir.

Daha fazla bilgiyi Android için Yerler SDK'sı ile İlgili Politikalar bölümünde bulabilirsiniz.