Text Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Developer Wilayah Ekonomi Eropa (EEA)

Text Search (Baru) menampilkan informasi tentang serangkaian tempat berdasarkan suatu string (misalnya, "pizza di Bandung" atau "toko sepatu di dekat Solo" atau "Jl. Rajawali 3"). Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang telah ditetapkan.

Selain parameter wajib, Text Search (Baru) mendukung penyempurnaan kueri menggunakan parameter opsional untuk mendapatkan hasil yang lebih baik.

Mendapatkan daftar tempat berdasarkan penelusuran teks

Buat permintaan Text Search dengan memanggil GMSPlacesClient searchByTextWithRequest:, meneruskan objek GMSPlaceSearchByTextRequest yang menentukan parameter permintaan dan metode callback, dari jenis GMSPlaceSearchByTextResultCallback, untuk menangani respons.

Objek GMSPlaceSearchByTextRequest menentukan semua parameter wajib dan opsional untuk permintaan. Parameter yang diperlukan mencakup:

  • Daftar kolom yang akan ditampilkan dalam objek GMSPlace, juga disebut masker kolom, seperti yang ditentukan oleh GMSPlaceProperty. Jika Anda tidak menentukan setidaknya satu kolom dalam daftar kolom, atau jika Anda menghapus daftar kolom, panggilan akan menampilkan error.
  • Kueri teks.

Contoh permintaan Text Search ini menentukan bahwa objek GMSPlace respons berisi nama tempat dan ID Tempat untuk setiap objek GMSPlace dalam hasil penelusuran. Kode ini juga memfilter respons agar hanya menampilkan tempat berjenis "restoran".

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;
      }
    }
  }
];

Respons Text Search

Text Search API menampilkan array kecocokan dalam bentuk objek GMSPlace, dengan satu objek GMSPlace per tempat yang cocok.

Mendapatkan status buka

Objek GMSPlacesClient berisi fungsi anggota bernama isOpenWithRequest (isOpenRequest di Swift dan isPlaceOpenRequest di GooglePlacesSwift) yang menampilkan respons yang menunjukkan apakah tempat tersebut saat ini buka, berdasarkan waktu yang ditentukan dalam panggilan.

Metode ini menggunakan satu argumen jenis GMSPlaceIsOpenWithRequest yang berisi:

  • Objek GMSPlace, atau string yang menentukan ID tempat. Untuk informasi selengkapnya tentang cara membuat objek Place dengan kolom yang diperlukan, lihat Place details.
  • Objek NSDate (Obj-C) atau Date (Swift) opsional yang menentukan waktu yang ingin Anda periksa. Jika tidak ada waktu yang ditentukan, defaultnya adalah sekarang.
  • Metode GMSPlaceOpenStatusResponseCallback untuk menangani respons.
    • >

Metode GMSPlaceIsOpenWithRequest mengharuskan kolom berikut ditetapkan dalam objek GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Jika kolom ini tidak disediakan dalam objek Place, atau jika Anda meneruskan ID tempat, metode ini akan menggunakan GMSPlacesClient GMSFetchPlaceRequest: untuk mengambilnya.

isOpenWithRequest tanggapan

isOpenWithRequest menampilkan objek GMSPlaceIsOpenResponse yang berisi nilai boolean bernama status yang menunjukkan apakah bisnis buka, tutup, atau statusnya tidak diketahui.

Language Nilai jika terbuka Nilai jika ditutup Nilai jika status tidak diketahui
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Penagihan untuk isOpenWithRequest

  • Kolom GMSPlacePropertyUTCOffsetMinutes dan GMSPlacePropertyBusinessStatus dikenai biaya berdasarkan SKU Basic Data. Jam Buka lainnya dikenai biaya berdasarkan SKU Place Details Enterprise.
  • Jika objek GMSPlace Anda sudah memiliki kolom ini dari permintaan sebelumnya, Anda tidak akan dikenai biaya lagi.

Contoh: Membuat permintaan GMSPlaceIsOpenWithRequest

Contoh berikut menunjukkan cara melakukan inisialisasi GMSPlaceIsOpenWithRequest dalam objek GMSPlace yang ada.

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
            }
          }];

Penomoran halaman

Text Search menyediakan objek penomoran halaman, boolean hasNextPage, yang ditampilkan dalam respons pertama terhadap panggilan Text Search. Jika halaman berikutnya tersedia, Anda dapat menggunakan fungsi fetchNextPage() untuk memuatnya.

Contoh berikut menunjukkan cara memeriksa apakah halaman berikutnya tersedia, lalu memuat halaman.

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];

Parameter yang diperlukan

Gunakan objek GMSPlaceSearchByTextRequest untuk menentukan parameter yang diperlukan untuk penelusuran.

  • Daftar kolom

    Tentukan properti data tempat yang akan ditampilkan. Teruskan daftar properti GMSPlace yang menentukan kolom data yang akan ditampilkan. Jika Anda menghapus mask kolom, permintaan akan menampilkan error.

    Daftar kolom merupakan praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan. Cara ini akan membantu Anda menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

    Tentukan satu atau beberapa kolom berikut:

    • Kolom berikut memicu SKU Text Search Essentials ID Only:

      GMSPlacePropertyPlaceID

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • Kolom berikut memicu SKU Text Search Pro:

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

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • Kolom berikut memicu SKU Text Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • Kolom berikut memicu SKU Text Search Enterprise Plus:

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

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

  • textQuery

    String teks yang digunakan untuk menelusuri, misalnya: "restaurant", "123 Main Street", atau "best place to visit in San Francisco".

Parameter opsional

Gunakan objek GMSPlaceSearchByTextRequest untuk menentukan parameter opsional untuk penelusuran.

  • includedType

    Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan yang didefinisikan oleh Tabel A. Hanya satu jenis yang dapat ditentukan. Contoh:

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

  • isOpenNow

    Jika true, hanya tampilkan tempat yang sedang buka pada saat kueri dikirim. Jika false, tampilkan semua bisnis terlepas dari status buka. Tempat yang tidak menetapkan jam buka dalam database Google Places akan ditampilkan jika Anda menetapkan parameter ini ke false.

  • isStrictTypeFiltering

    Digunakan dengan parameter includeType. Jika ditetapkan ke true, hanya tempat yang cocok dengan jenis yang ditentukan oleh includeType yang akan ditampilkan. Jika salah, yang merupakan default, respons dapat berisi tempat yang tidak cocok dengan jenis yang ditentukan.

  • locationBias

    Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias, yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan.

    Anda dapat menentukan locationRestriction atau locationBias, tetapi tidak keduanya. Anggap locationRestriction sebagai penentu wilayah tempat hasil harus berada, dan locationBias sebagai penentu wilayah tempat hasil harus berada di dekatnya, tetapi dapat berada di luar area tersebut.

    Tentukan wilayah sebagai Area Pandang persegi panjang atau sebagai lingkaran.

    • Lingkaran ditentukan oleh titik pusat dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius default-nya adalah 0,0. Contoh:

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

    • Persegi panjang adalah area pandang lintang-bujur, yang direpresentasikan sebagai dua titik rendah dan tinggi yang berlawanan secara diagonal. Titik rendah menandai sudut barat daya persegi panjang, dan titik tinggi mewakili sudut timur laut persegi panjang.

      Area pandang dianggap sebagai wilayah tertutup, yang berarti mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:

      • Jika low = high, area pandang terdiri dari satu titik tersebut.
      • Jika low.longitude > high.longitude, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat).
      • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang akan mencakup semua bujur.
      • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur akan kosong.
      • Jika low.latitude > high.latitude, rentang lintang kosong.

  • locationRestriction

    Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan. Tentukan wilayah sebagai Area Pandang persegi panjang. Lihat deskripsi locationBias untuk mengetahui informasi tentang cara menentukan Area Pandang.

    Anda dapat menentukan locationRestriction atau locationBias, tetapi tidak keduanya. Anggap locationRestriction sebagai penentu wilayah tempat hasil harus berada, dan locationBias sebagai penentu wilayah tempat hasil harus berada di dekatnya, tetapi dapat berada di luar area tersebut.

  • maxResultCount

    Menentukan jumlah maksimum hasil tempat yang akan ditampilkan. Harus antara 1 dan 20 (default) inklusif.

  • minRating

    Membatasi hasil hanya pada hasil yang rating pengguna rata-ratanya lebih besar dari atau sama dengan batas ini. Nilai harus antara 0,0 dan 5,0 (inklusif) dengan penambahan 0,5. Misalnya: 0, 0,5, 1,0, ... , 5,0 inklusif. Nilai dibulatkan ke atas ke 0,5 terdekat. Misalnya, nilai 0,6 akan menghilangkan semua hasil dengan rating kurang dari 1,0.

  • priceLevels

    Membatasi penelusuran ke tempat yang ditandai dengan tingkat harga tertentu. Setelan defaultnya adalah memilih semua tingkat harga.

    Tentukan array dari satu atau beberapa nilai yang ditentukan oleh PriceLevel.

    Contoh:

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

  • rankPreference

    Menentukan cara hasil diberi peringkat dalam respons berdasarkan jenis kueri:

    • Untuk kueri kategoris seperti "Restoran di Jakarta", .relevance (peringkat hasil berdasarkan relevansi penelusuran) adalah defaultnya. Anda dapat menetapkan rankPreference ke .relevance atau .distance (memberi peringkat hasil berdasarkan jarak).
    • Untuk kueri non-kategori seperti "Mountain View, CA", sebaiknya biarkan rankPreference tidak ditetapkan.

  • regionCode

    Kode wilayah yang digunakan untuk memformat respons, yang ditentukan sebagai nilai kode CLDR dua karakter. Parameter ini juga dapat memiliki efek bias pada hasil penelusuran. Tidak ada nilai default.

    Jika nama negara di kolom alamat dalam respons cocok dengan kode wilayah, kode negara akan dihilangkan dari alamat.

    Sebagian besar kode CLDR identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "The United Kingdom of Great Britain and Northern Ireland"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  • shouldIncludePureServiceAreaBusinesses

    Jika true, menampilkan bisnis jasa murni di hasil penelusuran. Bisnis jasa sistem panggilan murni adalah bisnis yang melakukan kunjungan atau pengiriman langsung ke pelanggan, tetapi tidak melayani pelanggan di alamat bisnisnya.

    Contoh:

    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;

Menampilkan atribusi dalam aplikasi Anda

Saat aplikasi Anda menampilkan informasi yang diperoleh dari GMSPlacesClient, seperti foto dan ulasan, aplikasi juga harus menampilkan atribusi yang diperlukan.

Misalnya, properti reviews dari objek GMSPlacesClient berisi array hingga lima objek GMSPlaceReview. Setiap objek GMSPlaceReview dapat berisi atribusi dan atribusi penulis. Jika Anda menampilkan ulasan di aplikasi, Anda juga harus menampilkan atribusi atau atribusi penulis.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi tentang atribusi.