Metin Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Metin Arama (Yeni), bir dizeye (örneğin, "New York'ta pizza", "Ottawa yakınlarındaki ayakkabı mağazaları" veya "123 Main Street") göre bir dizi yer hakkında bilgi döndürür. Hizmet, metin dizesiyle eşleşen ve belirlenmiş konum önyargısı olan yerlerin listesini döndürür.

Zorunlu parametrelere ek olarak, Metin Arama (Yeni), daha iyi sonuçlar için isteğe bağlı parametreler kullanılarak sorguların hassaslaştırılmasını destekler.

Metin Arama (Yeni), Yakında Arama (Yeni)'ya benzer. Bu iki yöntem arasındaki temel fark, Metin Arama (Yeni) yönteminde rastgele bir arama dizesi belirtebilirken Yakındaki Arama (Yeni) yönteminde arama yapılacak belirli bir alanın belirtilmesinin gerekmesidir.

Metin arama istekleri

Bir Text Search isteği şu biçimdedir:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

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

Bu örnekte:

  • Alan listesini yalnızca Place.Field.ID ve Place.Field.DISPLAY_NAME'yi içerecek şekilde ayarlayın. Bu nedenle, yanıttaki her eşleşen yeri temsil eden Place nesneleri yalnızca bu iki alanı içerir.

  • Aramayı tanımlayan bir SearchByTextRequest.Builder SearchByTextRequest nesnesi oluşturmak için kullanın.

    • Metin sorgusu dizesini "Acı Baharatlı Vejetaryen Yemek" olarak ayarlayın.

    • Maksimum sonuç yer sayısını 10 olarak ayarlayın. Varsayılan ve maksimum değer 20'dir.

    • Arama alanını enlem ve boylam koordinatlarıyla tanımlanan dikdörtgenle sınırlayın. Bu alanın dışındaki eşleşmeler döndürülmez.

  • OnSuccessListener ekleyin ve SearchByTextResponse nesnesinden eşleşen yerleri alın.

Metin Arama yanıtları

SearchByTextResponse sınıfı, bir arama isteğine verilen yanıtı temsil eder. SearchByTextResponse 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 listesiyle tanımlanan alanları içerir.

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_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 nesnesindeki 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.

Sayfalara ayırma

Text Search'ün SearchByTextResponse sınıfı, getPagination() yöntemi aracılığıyla metin arama sonucu sayfalandırmasına erişim sağlar. Bu yöntem, bir Pagination nesnesi döndürür.

Ek sonuç sayfalarının olup olmadığını belirlemek için sayfalandırma nesnesinin hasNextPage() yöntemini kullanın. Bu yöntem bir boole değeri (doğru veya yanlış) döndürür.

hasNextPage() doğru değerini döndürürken sonuçların sonraki sayfasını almak için fetchNextPage() yöntemini çağırın.

Aşağıdaki örnekte, sonraki sayfanın kullanılabilir olup olmadığını kontrol etme ve ardından sayfayı yükleme işlemi gösterilmektedir.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Gerekli parametreler

SearchByTextRequest için gerekli parametreler:

  • Alan listesi

    Hangi yer verisi alanlarının döndürüleceğini belirtin. Döndürülecek veri alanlarını belirten bir Place.Field değer listesi iletin. Yanıtta varsayılan olarak döndürülen alanların listesi yoktur.

    Alan listeleri, gereksiz veri istemediğinizden emin olmanızı sağlayan iyi bir tasarım uygulamasıdır. Bu sayede gereksiz işlem süresi ve faturalandırma ücretlerinden kaçınabilirsiniz.

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

    • Aşağıdaki alanlar Text Search Essentials ID Only SKU'yu (Yalnızca Kimlikli Text Search Essentials SKU'su) tetikler:

      Place.Field.DISPLAY_NAME*
          * Place.Field.NAME yerine kullanın (4.0 sürümünde desteği sonlandırılmıştır).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * places/PLACE_ID biçiminde yer kaynağı adını içerir.
           Yerin metin adına erişmek için DISPLAY_NAME tuşunu kullanın.

    • Aşağıdaki alanlar Text Search Pro SKU'sunu tetikler:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (desteği sonlandırıldı) yerine kullanılır.
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Place.Field.ADDRESS (desteği sonlandırıldı) yerine kullanın.
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Place.Field.ICON_URL (desteği sonlandırıldı) yerine kullanın.
      Place.Field.LOCATION*
          Place.Field.LAT_LNG (desteği sonlandırıldı) yerine kullanın.
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.SUB_DESTINATIONS
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT

    • Aşağıdaki alanlar Text Search Enterprise SKU'sunu tetikler:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Kullanımdan kaldırılan Place.Field.PHONE_NUMBER yerine kullanın.
      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*
          * Kullanımdan kaldırılan Place.Field.USER_RATINGS_TOTAL yerine kullanın.
      Place.Field.WEBSITE_URI

    • Aşağıdaki alanlar Text Search Enterprise Plus SKU'sunu 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

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

  • Metin sorgusu

    Aranacak metin dizesi (ör. "restoran", "123 Main Street" veya "San Francisco'da ziyaret edilebilecek en iyi yer"). API, bu dizeye göre olası eşleşmeleri döndürür ve sonuçları algılanan alaka düzeylerine göre sıralar.

    Metin sorgusu parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setTextQuery() yöntemini çağırın.

İsteğe bağlı parametreler

İsteğiniz için isteğe bağlı parametreleri belirtmek üzere SearchByTextRequest nesnesini kullanın.

  • Dahil edilen tür

    Sonuçları, A Tablosu'nda tanımlanan belirtilen türle eşleşen yerlerle sınırlar. Yalnızca bir tür belirtilebilir. Örneğin:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

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

  • Konum önyargısı

    Arama yapılacak bir alanı belirtir. Bu konum, bir önyargı olarak işlev görür. Bu nedenle, belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumla ilgili sonuçlar döndürülebilir.

    Konum kısıtlaması veya konum önyargısı belirtebilirsiniz ancak ikisini birden belirtemezsiniz. Konum kısıtlaması, sonuçların içinde olması gereken bölgeyi belirtmek, konum tercihi ise sonuçların büyük olasılıkla içinde veya yakınında olacağı bölgeyi belirtmek olarak düşünülebilir. Konum tercihi kullanılırken sonuçların belirtilen alanın dışında olabileceği unutulmamalıdır.

    Bölgeyi dikdörtgen bir görüntü alanı veya daire olarak belirtin.

    • Bir daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap 0,0 ile 50000,0 arasında (bu değerler dahil) olmalıdır. Örneğin:

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

    • Dikdörtgen, iki çapraz zıt düşük ve yüksek nokta olarak gösterilen bir enlem-boylam görüntü alanıdır. Düşük nokta, dikdörtgenin güneybatı köşesini, yüksek nokta ise dikdörtgenin kuzeydoğu köşesini temsil eder.

      Görüntü alanı, sınırını da içeren kapalı bir bölge olarak kabul edilir. Enlem sınırları -90 ile 90 derece arasında (bu değerler dahil), boylam sınırları ise -180 ile 180 derece arasında (bu değerler dahil) olmalıdır:

      • low = high ise görüntü alanı tek bir noktadan oluşur.
      • low.longitude > high.longitude ise boylam aralığı ters çevrilir (görüntü alanı 180 derece boylam çizgisini geçer).
      • low.longitude = -180 derece ve high.longitude = 180 derece ise görüntü alanı tüm boylamları içerir.
      • low.longitude = 180 derece ve high.longitude = -180 derece ise boylam aralığı boş olur.
      • low.latitude > high.latitude ise enlem aralığı boş olur.

      Hem düşük hem de yüksek değerler doldurulmalı ve gösterilen kutu boş olmamalıdır. Boş bir görünüm penceresi hataya neden olur.

      Örneğin, dikdörtgen bir görünüm penceresi için Metin Arama istekleri bölümüne bakın.

      Konum tercihi parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setLocationBias() yöntemini çağırın.

  • Konum kısıtlaması

    Arama yapılacak bir alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez. Bölgeyi dikdörtgen bir görüntü alanı olarak belirtin. Görünüm alanını tanımlama hakkında bilgi edinmek için Konum önyargısı açıklamasını inceleyin.

    Konum kısıtlaması veya konum önyargısı belirtebilirsiniz ancak ikisini birden belirtemezsiniz. Konum kısıtlamasını, sonuçların içinde olması gereken bölgeyi belirtme, konum tercihi ise sonuçların yakınında olması gereken ancak bölgenin dışında olabilecek bölgeyi belirtme olarak düşünebilirsiniz.

    Konum kısıtlama parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setLocationRestriction() 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 (bu değerler dahil).

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

  • Minimum kullanıcı oyu

    Sonuçları yalnızca ortalama kullanıcı puanı bu sınırdan yüksek veya bu sınıra eşit olanlarla kısıtlar. Değerler 0,5'lik artışlarla 0,0 ile 5,0 (başlangıç ve bitiş değerleri dahil) arasında olmalıdır. Örneğin: 0, 0.5, 1.0, ... , 5.0 (5.0 dahil). Değerler en yakın 0,5'e yuvarlanır. Örneğin, 0,6 değeri 1,0'dan düşük puanlı tüm sonuçları ortadan kaldırır.

    Minimum puan parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setMinRating() yöntemini çağırın.

  • Şu anda açık

    true ise yalnızca sorgu gönderildiğinde açık olan yerleri döndürün. false ise açık durumundan bağımsız olarak tüm işletmeleri döndürür. Google Yerler veritabanında çalışma saatleri belirtilmeyen yerler, bu parametreyi false olarak ayarlarsanız döndürülür.

    Şu anda açık parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setOpenNow() yöntemini çağırın.

  • Fiyat düzeyleri

    Sonuçlar varsayılan olarak her fiyat seviyesinde hizmet sunan yerleri içerir. Sonuçları yalnızca belirli fiyat seviyelerindeki yerleri içerecek şekilde kısıtlamak için döndürmek istediğiniz yerlerin fiyat seviyelerine karşılık gelen tam sayı değerlerinin bir listesini iletebilirsiniz:

    • 1 - Mekan, uygun fiyatlı hizmetler sunuyor.
    • 2 - Mekan, orta fiyatlı hizmetler sunuyor.
    • 3 - Yer, pahalı hizmetler sunuyor.
    • 4 - Place provides very expensive services.

    Fiyat seviyeleri parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setPriceLevels() yöntemini çağırın.

  • Sıralama tercihi

    Sonuçların, sorgu türüne göre yanıttaki sıralamasını belirtir:

    • "New York'taki restoranlar" gibi kategorik bir sorgu için varsayılan olarak SearchByTextRequest.RankPreference.RELEVANCE (sonuçları arama alaka düzeyine göre sırala) kullanılır. Sıralama tercihini SearchByTextRequest.RankPreference.RELEVANCE veya SearchByTextRequest.RankPreference.DISTANCE (sonuçları mesafeye göre sırala) olarak ayarlayabilirsiniz.
    • "Mountain View, CA" gibi kategorik olmayan bir sorgu için sıralama tercihi parametresini ayarlanmamış olarak bırakmanızı öneririz.

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

  • Bölge kodu

    Yanıtı biçimlendirmek için kullanılan bölge kodu, iki karakterli CLDR kodu değeri olarak belirtilir. Bu parametre, arama sonuçları üzerinde önyargı etkisi de yaratabilir. Varsayılan değer yoktur.

    Yanıtın adres alanındaki ülke adı, bölge koduyla eşleşiyorsa ülke kodu adresten çıkarılır.

    Bazı önemli istisnalar dışında çoğu CLDR kodu, ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu ise "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 SearchByTextRequest nesnesini oluştururken setRegionCode() yöntemini çağırın.

  • Katı tür filtreleme

    include türü parametresiyle birlikte kullanılır. true olarak ayarlandığında yalnızca include_type tarafından belirtilen türlerle eşleşen yerler döndürülür. Varsayılan değer olan false olduğunda yanıtta, belirtilen türlerle eşleşmeyen yerler olabilir.

    Katı tür filtreleme parametresini ayarlamak için SearchByTextRequest nesnesini oluştururken setStrictTypeFiltering() yöntemini çağırın.