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 yer grubu 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.

Metin aramasıyla yerlerin listesini alma

GMSPlacesClient searchByTextWithRequest: yöntemini çağırarak bir metin arama isteği gönderin. Bu yönteme, istek parametrelerini tanımlayan bir GMSPlaceSearchByTextRequest nesnesi ve yanıtı işlemek için GMSPlaceSearchByTextResultCallback türünde bir geri çağırma yöntemi iletin.

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

  • GMSPlace nesnesinde döndürülecek alanların listesi. GMSPlaceProperty tarafından tanımlandığı şekilde alan maskesi olarak da adlandırılır. Alan listesinde en az bir alan belirtmezseniz veya alan listesini atlarsanız çağrı bir hata döndürür.
  • Metin sorgusu.

Bu örnek metin arama isteği, yanıt GMSPlace nesnelerinin, arama sonuçlarındaki her bir GMSPlace nesnesi için yer adını ve yer kimliğini içerdiğini belirtir. Ayrıca, yanıtı yalnızca "restoran" türündeki yerleri döndürecek şekilde filtreler.

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

Text Search yanıtları

Text Search API, eşleşen her yer için bir GMSPlace nesnesi olacak şekilde GMSPlace nesneleri biçiminde bir eşleşme dizisi döndürür.

Açık durumunu alma

GMSPlacesClient nesnesi, çağrıda belirtilen zamana göre yerin şu anda açık olup olmadığını belirten bir yanıt döndüren isOpenWithRequest (Swift'te isOpenRequest ve GooglePlacesSwift'te isPlaceOpenRequest) adlı bir üye işlevi içerir.

Bu yöntem, aşağıdakileri içeren GMSPlaceIsOpenWithRequest türünde tek bir bağımsız değişken alır:

  • GMSPlace nesnesi veya yer kimliğini belirten bir dize. Gerekli alanları içeren Place nesnesini oluşturma hakkında daha fazla bilgi için Yer ayrıntıları başlıklı makaleyi inceleyin.
  • Kontrol etmek istediğiniz zamanı belirten isteğe bağlı bir NSDate (Obj-C) veya Date (Swift) nesnesi. Herhangi bir zaman belirtilmezse varsayılan olarak geçerli zaman kullanılır.
  • Yanıtı işlemek için bir GMSPlaceOpenStatusResponseCallback yöntemi.
    • >

GMSPlaceIsOpenWithRequest yöntemi, GMSPlace nesnesinde aşağıdaki alanların ayarlanmasını gerektirir:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Bu alanlar Place nesnesinde sağlanmazsa veya bir yer kimliği iletirseniz yöntem, bunları getirmek için GMSPlacesClient GMSFetchPlaceRequest: kullanır.

isOpenWithRequest yanıt

isOpenWithRequest, işletmenin açık veya kapalı olup olmadığını ya da durumun bilinip bilinmediğini gösteren status adlı bir boole değeri içeren GMSPlaceIsOpenResponse nesnesi döndürür.

Dil Açıksa değeri Kapalıysa değer Durum bilinmiyorsa değer
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

isOpenWithRequest için faturalandırma

  • GMSPlacePropertyUTCOffsetMinutes ve GMSPlacePropertyBusinessStatus alanları, Temel Veri SKU'su kapsamında ücretlendirilir. Çalışma saatleri ile ilgili diğer istekler Yer Ayrıntıları Kurumsal SKU'su kapsamında ücretlendirilir.
  • GMSPlace nesnenizde önceki bir istekten gelen bu alanlar zaten varsa tekrar ücretlendirilmezsiniz.

Örnek: GMSPlaceIsOpenWithRequest isteği gönderme

Aşağıdaki örnekte, mevcut bir GMSPlace nesnesi içinde GMSPlaceIsOpenWithRequest öğesinin nasıl ilk kullanıma hazırlanacağı gösterilmektedir.

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

Sayfalara ayırma

Metin Arama, Metin Arama çağrısına verilen ilk yanıtta döndürülen bir sayfalama nesnesi (hasNextPage boole değeri) sağlar. Sonraki bir sayfa varsa fetchNextPage() işlevini kullanarak bu sayfayı yükleyebilirsiniz.

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.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Gerekli parametreler

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

  • Alan listesi

    Döndürülecek yer verisi özelliklerini belirtir. Döndürülecek veri alanlarını belirten GMSPlace özelliklerinin listesini iletin. Alan maskesini atlarsanız istek bir hata döndürür.

    Alan listeleri, gereksiz veri istememenizi sağlayan iyi bir tasarım uygulamasıdır. Bu sayede gereksiz işlem süresinden 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:

      GMSPlacePropertyPlaceID

      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'sunu tetikler:

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

      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 SKU'sunu tetikler:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      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:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

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

  • textQuery

    Aranacak metin dizesi (ör. "restoran", "123 Main Street" veya "San Francisco'da ziyaret edilecek en iyi yer").

İsteğe bağlı parametreler

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

  • includedType

    Sonuçları, Tablo A'da tanımlanan belirtilen türle eşleşen yerlerle kısıtlar. Yalnızca bir tür belirtilebilir. Örneğin:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    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.

  • isStrictTypeFiltering

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

  • locationBias

    Arama yapılacak alanı belirtir. Bu konum, bir ön yargı görevi görür. Yani belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) döndürülebilir.

    locationRestriction veya locationBias değerini belirtebilirsiniz ancak ikisini birden belirtemezsiniz. locationRestriction parametresini, sonuçların içinde olması gereken bölgeyi belirten bir parametre, locationBias parametresini ise sonuçların yakınında olması gereken ancak alanın dışında olabileceği bölgeyi belirten bir parametre olarak düşünebilirsiniz.

    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. Varsayılan yarıçap 0,0'dır. Örneğin:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • Dikdörtgen, çapraz olarak karşılıklı iki alt ve üst nokta olarak temsil edilen 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ı, 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ı bu tek 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ştur.

  • locationRestriction

    Arama yapılacak 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üntü alanını tanımlama hakkında bilgi için locationBias açıklamasına bakın.

    locationRestriction veya locationBias değerini belirtebilirsiniz ancak ikisini birden belirtemezsiniz. locationRestriction parametresini, sonuçların içinde olması gereken bölgeyi belirten bir parametre, locationBias parametresini ise sonuçların yakınında olması gereken ancak alanın dışında olabileceği bölgeyi belirten bir parametre olarak düşünebilirsiniz.

  • maxResultCount

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

  • minRating

    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.

  • priceLevels

    Aramayı belirli fiyat seviyeleriyle işaretlenmiş yerlerle kısıtlayın. Varsayılan olarak tüm fiyat seviyeleri seçilir.

    PriceLevel tarafından tanımlanan bir veya daha fazla değerden oluşan bir dizi belirtin.

    Örneğin:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

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

    • "New York'taki restoranlar" gibi kategorik bir sorgu için varsayılan değer .relevance (sonuçları arama alaka düzeyine göre sırala) şeklindedir. rankPreference değerini .relevance veya .distance (sonuçları mesafeye göre sırala) olarak ayarlayabilirsiniz.
    • "Mountain View, CA" gibi kategorik olmayan bir sorgu için rankPreference parametresini ayarlamamanızı öneririz.

  • regionCode

    Yanıtı biçimlendirmek için kullanılan bölge kodu. İki 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.

  • shouldIncludePureServiceAreaBusinesses

    true ise arama sonuçlarında salt hizmet bölgesi işletmelerini döndürür. Salt hizmet bölgesi işletmesi, müşterileri doğrudan ziyaret eden veya onlara teslimat yapan ancak işletme adresinde müşterilere hizmet vermeyen işletmelerdir.

    Örneğin:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

Uygulamanızda ilişkilendirmeleri gösterme

Uygulamanız GMSPlacesClient üzerinden elde edilen bilgileri (ör. fotoğraflar ve yorumlar) gösterdiğinde gerekli atıfları da göstermelidir.

Örneğin, GMSPlacesClient nesnesinin reviews özelliği, en fazla beş GMSPlaceReview nesnesinden oluşan bir dizi içerir. Her GMSPlaceReview nesnesi, atıflar ve yazar atıfları içerebilir. Yorumu uygulamanızda gösteriyorsanız tüm atıfları veya yazar atıflarını da göstermeniz gerekir.

Daha fazla bilgi için ilişkilendirmeler ile ilgili belgelere bakın.