Yakındaki Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

Yakındakileri Ara (Yeni) isteği, daire olarak belirtilen arama bölgesini (çemberin merkez noktasının enlem ve boylam koordinatları ve yarıçapı metre cinsinden) giriş olarak alır. İstek, belirtilen arama alanındaki eşleşen yerlerin listesini döndürür. Bu liste, her biri bir Place nesnesi ile temsil edilen eşleşen yerlerin listesini döndürür.

Yanıt, varsayılan olarak arama alanındaki tüm türde yerleri içerir. İsteğe bağlı olarak, 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 yerlerin dahil edilmesini veya "okul" türündeki tüm yerlerin hariç tutulmasını belirtebilirsiniz.

Not: Yakındakiler Arama (Yeni), Android için Yerler SDK'sının 3.5.0 ve sonraki sürümlerinde kullanılabilir. Daha fazla bilgi için SDK sürümünüzü seçme başlıklı makaleyi inceleyin. 4.0.0 sürümünde eklenen Kotlin API'lerini kullanma hakkında daha fazla bilgi için Referans başlıklı makaleyi inceleyin.

Yakında Arama (Yeni) istekleri

PlacesClient.searchNearby işlevini çağırarak, istek parametrelerini tanımlayan bir SearchNearbyRequest nesnesi ile Yakındakileri Ara (Yeni) isteği gönderin.

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

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

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

// 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.DISPLAY_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();
    });

Not: PlacesClient'i başlatma hakkında daha fazla bilgi edinmek için Places API istemcisini başlatma başlıklı makaleyi inceleyin.

İstek sınıflarından herhangi birine (örneğin, FetchPlaceRequest) gönderilen bir isteği iptal etmek için CancellationToken kullanabilirsiniz. İptal işlemi, mümkün olduğunca yapılır. İptal isteği gönderildikten sonra yanıt verilmez. İptal jetonu göndermek, belirli bir isteğin iptal edileceğini GARANTİ ETMEZ. Ayrıca, yanıt gönderilmese bile istekten dolayı sizden ödeme alınabilir.

Yakında 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 tüm yerleri temsil eden Place nesnelerinin listesi. Eşleşen her yer için bir Place nesnesi bulunur.
• Her Place nesnesi yalnızca istekte iletilen alan listesi tarafından 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. Ardından, her Place nesnesinde bu alanlara erişmek için Place.getId() ve Place.getName() yöntemlerini kullanabilirsiniz.

Place nesnesindeki verilere erişmeyle ilgili daha fazla örnek için Yer nesnesi veri alanlarına erişme başlıklı makaleyi inceleyin.

Gerekli parametreler

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

• Alan listesi

  Yer ayrıntılarını istediğinizde, döndürülecek verileri yer için Place nesnesinde alan maskesi olarak belirtmeniz gerekir. Alan maskesini tanımlamak için Place.Field değerinden SearchNearbyRequest nesnesine bir değer dizisi iletin. Alan maskeleme, gereksiz veri istememenizi sağlamak için iyi bir tasarım uygulamasıdır. Bu sayede gereksiz işlem süresi ve faturalandırma ücretlerinden kaçınabilirsiniz.

  Aşağıdaki alanlardan en az birini belirtin:

  • Aşağıdaki alanlar Yakındaki 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.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, 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ındaki Arama (Gelişmiş) SKU'yu tetikler:

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Not:Place.Field.PHONE_NUMBER ve Place.Field.USER_RATINGS_TOTAL alanları, Android için Yerler SDK'sının 4.0 sürümünde kullanımdan kaldırıldı. Bunun yerine sırasıyla Place.Field.INTERNATIONAL_PHONE_NUMBER ve Place.USER_RATING_COUNT kullanın.

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

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Not: Android için Yerler SDK'sının 4.0 sürümünde, bazı Yer veri alanlarının desteği sonlandırıldı ve yeni alanlar eklendi. Daha fazla bilgi için Android 4.0 için Yerler SDK'sındaki yeni yer veri alanlarına geçiş başlıklı makaleyi inceleyin.

  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.DISPLAY_NAME alanlarını içerdiğini belirtmek için iki alan değerinin listesi 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.DISPLAY_NAME);

• Konum kısıtlaması

  Arama yapılacak bölgeyi daire olarak tanımlayan, merkez noktası ve yarıçapı metre cinsinden tanımlanan bir LocationRestriction nesnesi. Yarıçap, 0,0'dan büyük ve 50000,0'dan küçük veya eşit olmalıdır. Çok küçük bir yarıçap belirtmeniz durumunda yanıt olarak ZERO_RESULTS döndürüleceğ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 türlerin listesini belirtmenizi sağlar. Her tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.

  Not: B Tablosu'ndaki değerler yalnızca yanıtta döndürülür. B tablosundaki değerleri filtre olarak kullanamazsınız.

  Bir mekan, ilişkili Tablo A türleri arasından yalnızca tek bir birincil türe sahip olabilir. Ö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 değerlerini kullanın.

  Bir yerin, ilişkili Tablo A türlerinden birden fazla tür değeri de olabilir. Örneğin, bir restoranın şu türleri olabilir: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Bir yerle ilişkili tür listesinde sonuçları filtrelemek için includedTypes ve excludedTypes tuşlarını kullanın.

  "restaurant" veya "hotel" gibi genel bir birincil tür belirttiğinizde yanıt, belirtilenden daha spesifik bir birincil türe sahip yerler içerebilir. Örneğin, birincil "restaurant" türünü eklemeyi belirtirsiniz. Yanıt, birincil türü "restaurant" olan yerleri içerebilir ancak "chinese_restaurant" veya "seafood_restaurant" gibi daha spesifik birincil türlere sahip yerleri de içerebilir.

  Birden fazla tür kısıtlaması içeren bir arama yapılırsa 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 sunar ancak birincil olarak "steak_house" olarak faaliyet göstermez.

  includedTypes, excludedTypes, includedPrimaryTypes ve excludedPrimaryTypes parametrelerini istekten çıkarırsanız arama, konum kısıtlaması sınırları içindeki tüm türlerdeki yerleri döndürür.

  includedTypes ve excludedTypes'ün nasıl kullanılacağına dair bir örnek için Yakındakiler Arama (Yeni) isteklerine bakın.

  Dahil edilen türler

  A Tablosu'ndaki aranacak yer türlerinin listesi. Bu parametre atlanırsa tüm türde yerler 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 Tablo A'daki yer türlerinin listesi.

  İstekte hem includedTypes (ör. "school") hem de excludedTypes (ör. "primary_school") parametresini 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 ile en az bir, excludedTypes ile ise hiçbir eşleşmeyen yerleri içerir.

  Hem includedTypes hem de excludedTypes'te görünen bir tür gibi çelişen tür varsa 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 Tablo A'daki birincil yer türlerinin listesi.

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

  Hariç tutulan birincil türler

  Aramadan hariç tutulacak Tablo A'daki birincil yer türlerinin listesi.

  Hem includedPrimaryTypes hem de excludedPrimaryTypes'te görünen bir tür gibi birbiriyle çelişen 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 ile 20 (varsayılan) 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 atlanırsa 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 değer yoktur.

  Yanıttaki FORMATTED_ADDRESS alanının ülke adı regionCode ile eşleşirse ülke kodu FORMATTED_ADDRESS'ten çıkarılır.

  CLDR kodlarının çoğu, 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) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için). Parametre, geçerli yasaya göre sonuçları etkileyebilir.

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

Uygulamanızda ilişkilendirmeleri gösterme

Uygulamanız, PlacesClient'ten alınan fotoğraf ve yorumlar gibi bilgileri görüntülerken gerekli ilişkilendirmeleri de göstermelidir.

Daha fazla bilgi için Android için Yerler SDK'sı Politikaları başlıklı makaleyi inceleyin.