Nearby Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Fitur ini mengharuskan Anda mengaktifkan Places API (Baru), generasi berikutnya dari Places API. Untuk informasi selengkapnya, lihat Aktifkan API.

Permintaan Nearby Search (Baru) digunakan sebagai input wilayah yang akan ditelusuri ditetapkan sebagai lingkaran, yang didefinisikan oleh koordinat lintang dan bujur dari titik tengah lingkaran dan radius dalam meter. Permintaan tersebut menampilkan daftar tempat yang cocok, masing-masing diwakili oleh GMSPlace , dalam area penelusuran yang ditentukan.

Secara default, respons akan berisi semua jenis tempat dalam area penelusuran. Anda dapat memilih filter respons dengan menentukan daftar jenis tempat untuk secara eksplisit disertakan ke dalam atau dikecualikan dari yang dihasilkan. Misalnya, Anda dapat menentukan untuk hanya menyertakan tempat tersebut dalam respons yang berjenis "restaurant", "bakery", dan "cafe", atau kecualikan semua tempat yang berjenis "sekolah".

Permintaan Nearby Search (Baru)

Buat permintaan Nearby Search dengan menelepon GMSPlacesClient searchNearbyWithRequest:, meneruskan GMSPlaceSearchNearbyRequest yang mendefinisikan parameter permintaan dan metode callback, berjenis GMSPlaceSearchNearbyResultCallback, untuk menangani responsnya.

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

• Daftar kolom yang akan ditampilkan dalam objek GMSPlace, juga disebut sebagai field mask, seperti yang ditentukan oleh GMSPlaceProperty Jika Anda tidak menentukan setidaknya satu kolom dalam daftar kolom, atau jika Anda menghilangkan daftar kolom, maka panggilan akan menampilkan error.
• Pembatasan lokasi, artinya lingkaran yang menentukan area penelusuran.

Contoh permintaan penelusuran terdekat ini menetapkan bahwa objek GMSPlace respons berisi nama tempat (GMSPlacePropertyName) dan koordinat tempat (GMSPlacePropertyCoordinate) untuk setiap objek GMSPlace dalam penelusuran hasil pengujian tersebut. Fungsi ini juga memfilter respons agar hanya menampilkan tempat dengan jenis "restaurant" dan "cafe".

Swift

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

Objective-C

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

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

Places Swift SDK for iOS (Pratinjau)

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Respons Nearby Search

Nearby Search API mengembalikan susunan kecocokan dalam bentuk GMSPlace objek, dengan satu objek GMSPlace per tempat yang cocok.

Catatan: Kolom objek GMSPlace respons wajib diisi. Misalnya, jika daftar kolom menyertakan GMSPlacePropertyPhotos untuk meminta kolom photos sebagai respons, dan kolom photos dalam respons kosong, elemen ini akan dihilangkan dari objek GMSPlace respons.

Mendapatkan status buka

Objek GMSPlacesClient berisi fungsi anggota yang disebut 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.

Catatan: Fungsi GMSPlace isOpen: dan GMSPlace isOpenAtDate: yang tidak digunakan lagi mungkin tidak akurat dan tidak dimaksudkan untuk digunakan dengan Places API (Baru).

Metode ini mengambil satu argumen dari jenis GMSPlaceIsOpenWithRequest yang berisi:

• Objek GMSPlace, atau string yang menentukan ID tempat. Untuk informasi selengkapnya tentang membuat objek Tempat dengan kolom yang diperlukan, lihat Detail tempat.
  
  Catatan: Objek Tempat harus berisi ID tempat yang valid.
• 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 di objek GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Jika kolom ini tidak diberikan di objek Tempat, 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 apakah statusnya tidak diketahui.

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

Penagihan untuk isOpenWithRequest

• Kolom GMSPlacePropertyUTCOffsetMinutes dan GMSPlacePropertyBusinessStatus dikenai biaya berdasarkan SKU Basic Data. Sisa Jam Buka dikenai biaya berdasarkan SKU Place Details (Advanced).
• Jika objek GMSPlace Anda sudah memiliki kolom ini dari permintaan sebelumnya, Anda tidak akan ditagih lagi.
• Peringatan Jika objek GMSPlace Anda tidak memiliki kolom ini, Anda akan ditagih lagi untuk SKU Basic Data. Sisa Jam Buka dikenai biaya berdasarkan SKU Place Details (Advanced). Jika project Anda akan menggunakan isOpenWithRequest, sebaiknya pastikan Anda mengambil detail tempat yang diperlukan.

Contoh: Membuat permintaan GMSPlaceIsOpenWithRequest

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

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

GooglePlacesSwift

          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
          }
          

Parameter wajib

Gunakan objek GMSPlaceSearchNearbyRequest untuk menentukan parameter yang diperlukan untuk pencarian.

• Daftar kolom

  Saat meminta detail tempat, Anda harus menentukan data untuk ditampilkan dalam objek GMSPlace untuk tempat sebagai mask kolom. Untuk mendefinisikan {i>field mask<i}, teruskan sebuah {i>array<i} nilai dari GMSPlaceProperty ke objek GMSPlaceSearchNearbyRequest. Penyamaran kolom adalah praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan, Hal ini membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

  Tentukan satu atau beberapa kolom berikut:

  • Kolom berikut memicu metode SKU Nearby Search (Dasar):

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

  • Kolom berikut memicu metode SKU Nearby Search (Lanjutan):

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

  • Kolom berikut memicu metode SKU Nearby Search (Preferred):

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

  Contoh berikut ini meneruskan daftar dua nilai kolom untuk menentukan agar objek GMSPlace yang ditampilkan oleh permintaan berisi Kolom name dan placeID:

  Swift

  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

  Objective-C

  // Specify the place data types to return.
  NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
          

  Places Swift SDK for iOS (Pratinjau)

  // Specify the place data types to return.
  let fields: [PlaceProperty] = [.placeID, .displayName]
          

• locationRestriction

  GMSPlaceLocationRestriction yang mendefinisikan wilayah yang akan ditelusuri, ditetapkan sebagai sebuah lingkaran, yang didefinisikan berdasarkan titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius default-nya adalah 0,0. Dalam permintaan, Anda harus mengaturnya ke nilai yang lebih besar dari 0,0.

Parameter opsional

Gunakan objek GMSPlaceSearchNearbyRequest untuk menentukan parameter opsional untuk pencarian.

• includeTypes/excludedTypes, disertakanPrimaryTypes/excludedPrimaryTypes

  Memungkinkan Anda menentukan daftar jenis dari jenis Tabel A digunakan untuk memfilter hasil penelusuran. Maksimal 50 jenis dapat ditentukan dalam setiap kategori pembatasan jenis.

  Catatan: Nilai dalam Tabel B hanya ditampilkan dalam respons. Anda tidak dapat menggunakan nilai di Tabel B sebagai filter.

  Sebuah tempat hanya dapat memiliki satu jenis utama dari beberapa jenis Tabel A yang terkait dengan anotasi. Misalnya, tipe utama mungkin "mexican_restaurant" atau "steak_house". Gunakan includedPrimaryTypes dan excludedPrimaryTypes untuk memfilter hasil tipe utama tempat.

  Tempat juga dapat memiliki beberapa nilai jenis dari jenis Tabel A yang terkait dengannya. Misalnya, restoran mungkin memiliki jenis berikut: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Gunakan includedTypes dan excludedTypes untuk memfilter hasil pada daftar jenis yang terkait dengan di suatu tempat.

  Saat Anda menentukan jenis utama umum, seperti "restaurant" atau "hotel", respons dapat berisi tempat dengan jenis utama yang lebih spesifik daripada yang ditentukan. Misalnya, Anda menetapkan untuk menyertakan jenis utama "restaurant". Responsnya kemudian bisa berisi tempat dengan tipe utama "restaurant", tetapi responsnya juga dapat berisi tempat dengan jenis utama, seperti "chinese_restaurant" atau "seafood_restaurant".

  Jika penelusuran ditentukan dengan beberapa pembatasan jenis, hanya tempat yang memenuhi semua batasan akan ditampilkan. Misalnya, jika Anda menentukan {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, tempat yang ditampilkan menyediakan layanan terkait "restaurant", tetapi tidak beroperasi secara utama sebagai "steak_house".

  Jika Anda menghilangkan includedTypes, excludedTypes, includedPrimaryTypes, dan excludedPrimaryTypes dari permintaan, penelusuran akan menampilkan tempat untuk semua jenis dari dalam batas pembatasan lokasi.

  includedTypes

  Daftar jenis tempat dari Tabel A yang akan ditelusuri. Jika parameter ini dihilangkan, semua jenis tempat akan ditampilkan.

  excludedTypes

  Daftar jenis tempat dari Tabel A yang akan dikecualikan dari cari.

  Jika Anda menentukan includedTypes (seperti "school") dan excludedTypes (seperti "primary_school") dalam permintaan, lalu menyertakan tempat yang dikategorikan sebagai "school", tetapi bukan sebagai "primary_school". Respons mencakup tempat yang cocok dengan setidaknya salah satu dari includedTypes dan tidak satu pun dari excludedTypes.

  Jika ada jenis yang bertentangan, seperti jenis yang muncul di kedua includedTypes dan excludedTypes, error INVALID_REQUEST akan ditampilkan.

  includedPrimaryTypes

  Daftar jenis tempat utama dari Tabel A yang akan disertakan dalam penelusuran.

  excludedPrimaryTypes

  Daftar jenis tempat utama dari Tabel A yang akan dikecualikan dari penelusuran.

  Jika ada jenis utama yang bertentangan, seperti jenis yang muncul di kedua includedPrimaryTypes dan excludedPrimaryTypes, INVALID_ARGUMENT error yang ditampilkan.

• maxResultCount

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

• rankPreference

  Jenis peringkat yang akan digunakan. Jika parameter ini dihilangkan, hasil akan diurutkan berdasarkan popularitas. Mungkin berupa salah satu dari hal berikut:

  • .popularity (default) Mengurutkan hasil berdasarkan popularitasnya.
  • .distance Mengurutkan hasil dalam urutan menaik berdasarkan jaraknya dari lokasi yang ditentukan.

• regionCode

  Kode wilayah yang digunakan untuk memformat respons, yang ditetapkan sebagai kode CLDR dua karakter. Tidak ada nilai default.

  Jika nama negara kolom formattedAddress dalam respons cocok dengan regionCode, kode negara dihilangkan dari formattedAddress. Parameter ini tidak berpengaruh pada adrFormatAddress, yang selalu menyertakan negara nama, atau pada shortFormattedAddress, yang tidak pernah menyertakannya.

  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 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 GMSPlaceReview objek terstruktur dalam jumlah besar. Setiap objek GMSPlaceReview dapat berisi atribusi dan atribusi penulis. Jika Anda menampilkan ulasan di aplikasi, Anda juga harus menampilkan atribusi atau penulis atribusi.

Untuk informasi selengkapnya, lihat dokumentasi di atribusi.