Text Search (Baru)

Text Search menampilkan informasi tentang serangkaian tempat berdasarkan sebuah string. Misalnya, "pizza di New York", "toko sepatu dekat Ottawa", atau "123 Main Street". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang ditetapkan.

Layanan ini sangat berguna untuk membuat kueri alamat yang ambigu dalam sistem otomatis, dan komponen non-alamat pada string mungkin cocok dengan bisnis serta alamat. Contoh kueri alamat ambigu adalah alamat yang diformat dengan buruk atau permintaan yang menyertakan komponen bukan alamat, seperti nama bisnis. Permintaan seperti dua contoh pertama mungkin menampilkan hasil nol, kecuali jika lokasi (seperti batasan wilayah, pembatasan lokasi, atau bias lokasi) ditetapkan.

"10 High Street, UK" atau "123 Main Street, US" Beberapa "High Street" di Inggris; beberapa "Main Street" di AS. Kueri tidak menampilkan hasil yang diinginkan kecuali jika pembatasan lokasi ditetapkan.
"Jaringan restoran New York" Beberapa lokasi "Jaringan restoran" di New York; tidak ada alamat atau bahkan nama jalan.
"10 High Street, Escher UK" atau "123 Main Street, Pleasanton US" Hanya satu "High Street" di kota Escher, Inggris Raya; hanya satu "Main Street" di kota Pleasanton CA, AS.
"Nama Restoran Unik Jakarta" Hanya satu perusahaan dengan nama ini di New York; tidak ada alamat yang perlu digunakan untuk membedakannya.
"restoran pizza di Jakarta" Kueri ini berisi pembatasan lokasinya, dan "restoran pizza" adalah jenis tempat yang ditentukan dengan baik. Metode ini menampilkan beberapa hasil.
"+1 514-670-8700"

Kueri ini berisi nomor telepon. Metode ini akan menampilkan beberapa hasil untuk tempat yang terkait dengan nomor telepon tersebut.

Mendapatkan daftar tempat berdasarkan penelusuran teks

Buat permintaan Text Search dengan memanggil GMSPlacesClient searchByTextWithRequest:, dengan meneruskan objek GMSPlaceSearchByTextRequest yang menentukan parameter permintaan dan metode callback, berjenis 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 mask kolom, seperti yang ditentukan oleh GMSPlaceProperty. Jika Anda tidak menentukan setidaknya satu kolom dalam daftar kolom, atau jika Anda menghilangkan daftar kolom, panggilan akan menampilkan error.
  • Kueri teks.

Contoh permintaan penelusuran teks 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 "restaurant".

Swift

// Create the GMSPlaceSearchByTextRequest object.
let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID];
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
request.locationRestriction = GMSPlaceRectangularLocationOption(
      CLLocationCoordinate2D(latitude: 20, longitude: 30),
      CLLocationCoordinate2D(latitude: 40, longitude: 50)
)

// Array to hold the places in the response
placeResults = [];

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
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchByTextWithRequest(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.locationRestriction = GMSPlaceRectangularLocationOption(
    CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50));
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.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 (placeResults.count > 0) {
      // Get list of places.
      _placeResults = placeResults;
  }
}];

GooglePlacesSwift

let restriction = RectangularLocationRestriction(
      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
}

Respons Text Search

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

Bersama dengan kolom data, objek GMSPlace dalam respons berisi fungsi anggota berikut:

  • isOpen menghitung apakah suatu tempat buka pada waktu tertentu.
  • isOpenAtDate menghitung apakah tempat buka pada tanggal tertentu atau tidak.

Parameter wajib

Gunakan objek GMSPlaceSearchByTextRequest untuk menentukan parameter yang diperlukan untuk penelusuran.

  • Daftar kolom

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

    Daftar kolom adalah praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak perlu, yang membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

    Tentukan satu atau beberapa kolom berikut:

    • Kolom berikut memicu SKU Text Search (ID Only):

      GMSPlacePropertyPlaceID, GMSPlacePropertyName

    • Kolom berikut memicu SKU Text Search (Basic):

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

    • Kolom berikut memicu SKU Text Search (Advanced):

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

    • Kolom berikut memicu SKU Text Search (Preferred):

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

  • textQuery

    String teks yang digunakan untuk menelusuri, misalnya: "restaurant", "123 Main Street", atau "tempat terbaik untuk dikunjungi di 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 ditentukan oleh Tabel A. Hanya satu jenis yang dapat ditentukan. Contoh:

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

    Jika true, hanya tampilkan tempat yang sedang buka pada saat kueri dikirim. Jika false, tampilkan semua bisnis terlepas dari status bukanya. 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 tertentu yang ditentukan oleh includeType yang akan ditampilkan. Jika false, respons default 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. Bayangkan locationRestriction sebagai menentukan wilayah tempat hasil harus berada, dan locationBias menentukan wilayah tempat hasil harus dekat, tetapi bisa saja di luar area tersebut.

    Tentukan wilayah sebagai Area Pandang persegi panjang atau lingkaran.

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

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)

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

      Area pandang dianggap sebagai area tertutup, yang berarti area pandang tersebut menyertakan batasnya. Batas garis lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus memiliki rentang antara -180 hingga 180 derajat:

      • Jika low = high, area tampilan 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 tampilan akan mencakup semua bujur.
      • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujurnya kosong.
      • Jika low.latitude > high.latitude, rentang lintang akan 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 informasi tentang menentukan Area Pandang.

    Anda dapat menentukan locationRestriction atau locationBias, tetapi tidak keduanya. Bayangkan locationRestriction sebagai menentukan wilayah tempat hasil harus berada, dan locationBias menentukan wilayah tempat hasil harus dekat, tetapi bisa saja di luar area tersebut.

  • maxResultCount

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

  • minRating

    Membatasi hasil hanya untuk hasil yang rating penggunanya rata-rata lebih besar dari atau sama dengan batas ini. Nilai harus antara 0,0 dan 5,0 (inklusif) dengan kelipatan 0,5. Misalnya: 0, 0.5, 1.0, ... , 5.0 inklusif. Nilai dibulatkan ke atas ke 0,5 terdekat. Misalnya, nilai 0,6 akan menghapus semua hasil dengan rating kurang dari 1,0.

  • priceLevels

    Membatasi penelusuran ke tempat yang ditandai di tingkat harga tertentu. Setelan default-nya adalah memilih semua tingkat harga.

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

    Contoh:

    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    Menentukan cara peringkat hasil dalam respons berdasarkan jenis kueri:

    • Untuk kueri kategori seperti "Restoran di Bandung", .relevance (peringkat hasil berdasarkan relevansi penelusuran) adalah default. Anda dapat menetapkan rankPreference ke .relevance atau .distance (beri peringkat hasil berdasarkan jarak).
    • Untuk kueri non-kategori seperti "Stackdriver View, CA", sebaiknya biarkan rankPreference tidak ditetapkan.

  • regionCode

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

    Jika nama negara untuk 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 "Inggris Raya dan Irlandia Utara"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

Menampilkan atribusi dalam aplikasi Anda

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

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

Untuk informasi selengkapnya, lihat dokumentasi tentang atribusi.