Metin Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

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

Text Search (New), bir dizeye (ör. "New York'ta pizza", "Ottawa yakınlarındaki ayakkabı mağazaları" veya "123 Main Street") dayalı olarak bir dizi yer hakkında bilgi döndürür. Hizmet, metin dizesiyle ve ayarlanmış konum tercihiyle eşleşen yerlerin listesini döndürür.

Text Search (Yeni), zorunlu parametrelerin yanı sıra daha iyi sonuçlar için isteğe bağlı parametreleri kullanarak sorguları hassaslaştırmayı destekler.

Text Search (New), Yakında Arama (New)'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

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, yanıtta eşleşen her yeri temsil eden Place nesnelerinin yalnızca bu iki alanı içerdiği anlamına gelir.

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

    • Metin sorgu dizesini "Spicy Vegetarian Food" olarak ayarlayın.

    • Maksimum sonuç yeri 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 eşleşen yerleri SearchByTextResponse nesnesinden alın.

Text Search yanıtları

SearchByTextResponse sınıfı, bir arama isteğinden gelen yanıtı temsil eder. Bir 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 listesi tarafından 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 bir Place nesnesinin yalnızca eşleşen her yerin kimliğini ve adını içerdiği anlamına gelir. Ardından, her bir 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ı, Pagination nesnesi döndüren getPagination() yöntemiyle metin arama sonucu sayfalandırmasına erişim sağlar.

Ek sonuç sayfalarının olup olmadığını belirlemek için Pagination nesnesinin hasNextPage() yöntemini kullanın. Bu yöntem bir boole değeri (true veya false) döndürür.

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

Aşağıdaki örnekte, sonraki bir sayfanın mevcut olup olmadığının nasıl kontrol edileceği ve ardından sayfanın nasıl yükleneceği 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 şunlardır:

  • 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ğerleri listesi iletin. Yanıtta döndürülen alanların varsayılan bir listesi yoktur.

    Alan listeleri, gereksiz veri istememenizi 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 tetikler:

      Place.Field.DISPLAY_NAME*
          * Place.Field.NAME (4.0 sürümünde desteği sonlandırıldı) yerine kullanın.
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Şu biçimdeki yer kaynağı adını içerir: places/PLACE_ID.
           Yerin metin adına erişmek için DISPLAY_NAME simgesini kullanın.

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

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

      Place.Field.ACCESSIBILITY_OPTIONS*
          Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (desteği sonlandırıldı) yerine kullanın.
      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

      Alanların ve ilişkili SKU'larının tam listesi için Yer Veri Alanları (Yeni) başlıklı makaleyi inceleyin.

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

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Desteği sonlandı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*
          * Desteği sonlandırılan Place.Field.USER_RATINGS_TOTAL yerine kullanın.
      Place.Field.WEBSITE_URI

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

    • 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

      Alanların ve ilişkili SKU'larının tam listesi için Yer Veri Alanları (Yeni) başlıklı makaleyi inceleyin.

    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 edilecek en iyi yer"). API, bu dizeye göre aday 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ı, Tablo A'da 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 yanlılığı

    Arama yapılacak alanı belirtir. Bu konum, bir eğilim olarak kullanılır. Yani belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) döndürülebilir.

    Konum kısıtlaması veya konum tercihi belirtebilirsiniz ancak ikisini birden belirtemezsiniz. Konum kısıtlamasını, sonuçların içinde olması gereken bölgeyi belirtmek, konum eğilimini ise sonuçların içinde veya yakınında olacağı bölgeyi belirtmek olarak düşünebilirsiniz. Konum eğilimini kullanırken sonuçların belirtilen alanın dışında da olabileceğini unutmayın.

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

    • Daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap, 0,0 ile 50.000,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, enlem-boylam görünüm penceresidir ve çapraz olarak zıt iki düşük ve yüksek nokta olarak gösterilir. 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ı, kapalı bir bölge olarak kabul edilir. Yani sınırını da içerir. 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ştur.
      • low.latitude > high.latitude ise enlem aralığı boş olur.

      Hem düşük hem de yüksek değer doldurulmalıdır ve gösterilen kutu boş olamaz. Boş bir görüntü alanı hataya neden olur.

      Örneğin, dikdörtgen görüntü alanı 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ı bölümündeki açıklamayı inceleyin.

    Konum kısıtlaması veya konum tercihi belirtebilirsiniz ancak ikisini birden belirtemezsiniz. Konum kısıtlamasını, sonuçların içinde olması gereken bölgeyi belirtmek, konum eğilimini ise sonuçların yakınında olması gereken ancak bölgenin dışında olabileceği bölgeyi belirtmek 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.

    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ıra eşit veya bu sınırdan yüksek olanlarla kısıtlar. Değerler 0,0 ile 5,0 (başlangıç ve bitiş değerleri dahil) arasında olmalı ve 0,5'lik artışlarla yükselmelidir. Örneğin: 0, 0,5, 1,0, ... , 5,0 dahil. Değerler en yakın 0,5 değerine yuvarlanır. Örneğin, 0,6 değeri, derecelendirmesi 1,0'dan düşük olan tüm sonuçları eler.

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

  • Şu anda açık

    true ise yalnızca sorgunun gönderildiği sırada açık olan yerleri döndürür. false ise açık durumuna bakılmaksızın tüm işletmeleri döndür. Bu parametreyi false olarak ayarlarsanız Google Places veritabanında çalışma saatleri belirtilmeyen yerler 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 listesini iletebilirsiniz:

    • 1 - Mekanda ucuz hizmetler sunulur.
    • 2 - Mekan, uygun fiyatlı hizmetler sunuyor.
    • 3: Tesis, pahalı hizmetler sunuyor.
    • 4 - Place provides very expensive services.

    Fiyat düzeyleri parametresini ayarlamak için SearchByTextRequest nesnesi oluşturulurken setPriceLevels() yöntemini çağırın.

  • Sıralama tercihi

    Sorgu türüne göre yanıttaki sonuçların nasıl sıralanacağını belirtir:

    • "İstanbul'daki 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 yanlılık etkisi de gösterebilir. Varsayılan değer yoktur.

    Yanıttaki adres alanının ülke adı bölge koduyla eşleşirse ülke kodu adresten çıkarılır.

    Çoğu CLDR kodu, ISO 3166-1 kodlarıyla aynıdır ancak bazı önemli istisnalar vardı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 SearchByTextRequest nesnesini oluştururken setRegionCode() yöntemini çağırın.

  • Katı tür filtreleme

    include type parametresiyle birlikte kullanılır. true olarak ayarlandığında, yalnızca include_type ile belirtilen türlerle eşleşen yerler döndürülür. Varsayılan değer olan false kullanıldığında yanıt, belirtilen türlerle eşleşmeyen yerler içerebilir.

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