Nearby Search (Baru)

Permintaan Nearby Search (Baru) mengambil wilayah sebagai input untuk penelusuran yang ditetapkan sebagai lingkaran, yang ditentukan oleh koordinat lintang dan bujur titik pusat lingkaran dan radius dalam meter. Permintaan ini menampilkan daftar tempat yang cocok, masing-masing diwakili oleh objek GMSPlace, dalam area penelusuran yang ditentukan.

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

Permintaan Nearby Search (Baru)

Buat permintaan Nearby Search dengan memanggil GMSPlacesClient searchNearbyWithRequest:, dengan meneruskan objek GMSPlaceSearchNearbyRequest yang menentukan parameter permintaan dan metode callback, berjenis GMSPlaceSearchNearbyResultCallback, untuk menangani respons.

Objek GMSPlaceSearchNearbyRequest 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.
  • Pembatasan lokasi, artinya lingkaran yang menentukan area penelusuran.

Contoh permintaan penelusuran terdekat ini menentukan bahwa objek GMSPlace respons berisi nama tempat (GMSPlacePropertyName) dan koordinat tempat (GMSPlacePropertyCoordinate) untuk setiap objek GMSPlace dalam hasil penelusuran. Kode ini juga memfilter respons agar hanya menampilkan tempat berjenis "restaurant" dan "cafe".

Swift

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

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

GMSPlacesClient.shared().searchNearbyWithRequest(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) {
      [weakSelf showErrorWithMessage:error.localizedDescription];
    } else {
      // Get list of places.
      _placeResults = places;

    }
  }
];

GooglePlacesSwift

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 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 GMSPlaceSearchNearbyRequest untuk menentukan parameter yang diperlukan untuk penelusuran.

  • Daftar kolom

    Saat meminta detail tempat, Anda harus menentukan data yang akan ditampilkan dalam objek GMSPlace untuk tempat sebagai mask kolom. Untuk menentukan mask kolom, teruskan array nilai dari GMSPlaceProperty ke objek GMSPlaceSearchNearbyRequest. Penyamaran 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 Nearby Search (Basic):

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

    • Kolom berikut memicu SKU Nearby Search (Advanced):

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

    • Kolom berikut memicu SKU Nearby Search (Preferred):

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

    Contoh berikut meneruskan daftar dua nilai kolom untuk menentukan bahwa 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];

    GooglePlacesSwift

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

  • locationRestriction

    Objek GMSPlaceLocationRestriction yang menentukan wilayah untuk ditelusuri yang ditetapkan sebagai lingkaran, yang ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000.0, inklusif. Radius default adalah 0,0. Dalam permintaan Anda, Anda harus menetapkannya ke nilai yang lebih besar dari 0,0.

Parameter opsional

Gunakan objek GMSPlaceSearchNearbyRequest untuk menentukan parameter opsional untuk penelusuran.

  • includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

    Sebuah tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A yang terkait dengannya. Misalnya, jenis utamanya mungkin "mexican_restaurant" atau "steak_house". Gunakan includedPrimaryTypes dan excludedPrimaryTypes untuk memfilter hasil pada jenis utama suatu tempat.

    Suatu 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 tempat.

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

    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 penelusuran.

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

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

    includedPrimaryTypes

    Daftar jenis tempat utama dari Tabel A untuk 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 includedPrimaryTypes dan excludedPrimaryTypes, error INVALID_ARGUMENT akan 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 diberi peringkat berdasarkan popularitas. Dapat berupa salah satu dari yang 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 nilai kode CLDR dua karakter. Tidak ada nilai default.

    Jika nama negara untuk kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihapus dari formattedAddress. Parameter ini tidak berpengaruh pada adrFormatAddress, yang selalu menyertakan nama negara, 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 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.