Tìm kiếm lân cận (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Yêu cầu Tìm kiếm lân cận (Mới) nhập khu vực để tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bởi vĩ độ và kinh độ của điểm giữa của vòng tròn và bán kính tính bằng mét. Yêu cầu trả về một danh sách các địa điểm phù hợp, mỗi địa điểm được thể hiện bằng một GMSPlace trong khu vực tìm kiếm được chỉ định.

Theo mặc định, câu trả lời sẽ chứa mọi loại địa điểm thuộc khu vực tìm kiếm. Bạn có thể tuỳ ý lọc phản hồi bằng cách chỉ định danh sách các loại địa điểm để bao gồm hoặc loại trừ một cách rõ ràng khỏi của bạn. Ví dụ: bạn có thể chỉ định chỉ đưa những địa điểm đó vào câu trả lời thuộc loại "nhà hàng", "tiệm bánh" và "quán cà phê" hoặc loại trừ tất cả địa điểm thuộc loại "trường học".

Yêu cầu Tìm kiếm lân cận (Mới)

Đưa ra yêu cầu Tìm kiếm lân cận bằng cách gọi GMSPlacesClient searchNearbyWithRequest:! truyền một GMSPlaceSearchNearbyRequest xác định các thông số yêu cầu và phương thức gọi lại, thuộc loại GMSPlaceSearchNearbyResultCallback! để xử lý phản hồi.

Đối tượng GMSPlaceSearchNearbyRequest chỉ định tất cả bắt buộc và không bắt buộc cho yêu cầu. Các tham số bắt buộc bao gồm:

  • Danh sách trường cần trả về trong đối tượng GMSPlace, còn được gọi là fieldMask (mặt nạ trường), như được xác định bởi GMSPlaceProperty. Nếu bạn không chỉ định ít nhất một trường trong danh sách trường hoặc nếu bạn bỏ qua danh sách trường thì lệnh gọi sẽ trả về lỗi.
  • Hạn chế vị trí, nghĩa là vòng tròn xác định khu vực tìm kiếm.

Ví dụ về yêu cầu tìm kiếm lân cận này chỉ định rằng các đối tượng GMSPlace phản hồi chứa tên địa điểm (GMSPlacePropertyName) và toạ độ của địa điểm (GMSPlacePropertyCoordinate) cho mỗi đối tượng GMSPlace trong tìm kiếm kết quả. API này cũng lọc câu trả lời để chỉ trả về các địa điểm thuộc loại "nhà hàng" và "quán cà phê".

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

SDK Swift địa điểm dành cho iOS (Xem trước)

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
}

Phản hồi cho tính năng Tìm kiếm lân cận

API Tìm kiếm lân cận trả về một mảng các kết quả trùng khớp ở dạng GMSPlace với một đối tượng GMSPlace cho mỗi vị trí phù hợp.

Xem trạng thái mở cửa

Đối tượng GMSPlacesClient chứa một hàm thành phần có tên là isOpenWithRequest (isOpenRequest trong Swift và isPlaceOpenRequest trong GooglePlacesSwift) sẽ trả về một phản hồi cho biết địa điểm hiện có mở cửa hay không, dựa trên thời gian được chỉ định trong cuộc gọi.

Phương thức này lấy một đối số duy nhất thuộc loại GMSPlaceIsOpenWithRequest chứa:

  • Đối tượng GMSPlace hoặc một chuỗi chỉ định mã địa điểm. Để biết thêm thông tin về cách tạo đối tượng Địa điểm với các trường cần thiết, hãy xem phần Thông tin chi tiết về địa điểm.
  • Đối tượng NSDate (Obj-C) hoặc Date (Swift) (không bắt buộc) chỉ định thời gian bạn muốn kiểm tra. Nếu bạn không chỉ định thời gian, giá trị mặc định sẽ là ngay bây giờ.
  • Phương thức GMSPlaceOpenStatusResponseCallback để xử lý phản hồi.
    • &gt;

Phương thức GMSPlaceIsOpenWithRequest yêu cầu bạn phải đặt các trường sau trong đối tượng GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Nếu các trường này không được cung cấp trong đối tượng Địa điểm hoặc nếu bạn truyền mã địa điểm, thì phương thức này sẽ sử dụng GMSPlacesClient GMSFetchPlaceRequest: để tìm nạp các trường đó.

isOpenWithRequest câu trả lời

isOpenWithRequest trả về một đối tượng GMSPlaceIsOpenResponse chứa giá trị boolean có tên status. Giá trị này cho biết doanh nghiệp đang mở cửa, đã đóng cửa hay không xác định được trạng thái.

Ngôn ngữ Giá trị nếu mở Giá trị nếu đóng Giá trị nếu trạng thái không xác định
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (Bản xem trước) true false nil

Thanh toán cho isOpenWithRequest

Ví dụ: Tạo yêu cầu GMSPlaceIsOpenWithRequest

Ví dụ sau đây cho thấy cách khởi tạo GMSPlaceIsOpenWithRequest trong đối tượng GMSPlace hiện có.

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
          }

Thông số bắt buộc

Sử dụng đối tượng GMSPlaceSearchNearbyRequest để chỉ định các tham số bắt buộc cho nội dung tìm kiếm.

  • Danh sách trường

    Khi bạn yêu cầu thông tin chi tiết về địa điểm, bạn phải chỉ định dữ liệu để trả về trong đối tượng GMSPlace cho địa điểm dưới dạng mặt nạ trường. Để xác định mặt nạ trường, chuyển một mảng các giá trị từ GMSPlaceProperty cho đối tượng GMSPlaceSearchNearbyRequest. Tạo mặt nạ cho trường là một phương pháp thiết kế tốt để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và các khoản phí thanh toán không cần thiết.

    Chỉ định một hoặc nhiều trường sau:

    • Sau đây là các trường kích hoạt SKU của Tìm kiếm lân cận (Cơ bản):

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

    • Sau đây là các trường kích hoạt SKU của tính năng Tìm kiếm lân cận (Nâng cao):

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

    • Sau đây là các trường kích hoạt SKU của tính năng Tìm kiếm lân cận (Ưu tiên):

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

    Ví dụ sau truyền danh sách hai giá trị trường để chỉ định rằng đối tượng GMSPlace được yêu cầu trả về sẽ chứa Các trường name và 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];

    SDK Swift địa điểm dành cho iOS (Xem trước)

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

  • locationRestriction

    GMSPlaceLocationRestriction đối tượng xác định vùng cần tìm kiếm được chỉ định dưới dạng một hình tròn, được xác định bởi điểm giữa và bán kính tính theo mét. Bán kính phải nằm trong khoảng từ 0,0 đến 50000,0, bao gồm cả hai giá trị đó. Bán kính mặc định là 0,0. Bạn phải đặt giá trị này trong yêu cầu của mình thành một giá trị lớn hơn 0,0.

Thông số tùy chọn

Sử dụng đối tượng GMSPlaceSearchNearbyRequest để chỉ định các tham số không bắt buộc cho nội dung tìm kiếm.

  • includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

    Cho phép bạn chỉ định danh sách các loại trong các loại Bảng A dùng để lọc kết quả tìm kiếm. Bạn có thể chỉ định tối đa 50 loại trong mỗi danh mục hạn chế loại.

    Một địa điểm chỉ có thể có một loại chính duy nhất trong các loại Bảng A được liên kết với nó. Ví dụ: loại chính có thể là "mexican_restaurant" hoặc "steak_house". Sử dụng includedPrimaryTypes và excludedPrimaryTypes để lọc kết quả loại hình chính của một địa điểm.

    Một địa điểm cũng có thể có nhiều giá trị loại từ các loại Bảng A liên kết với cuộc trò chuyện đó. Ví dụ: một nhà hàng có thể có các loại sau: "seafood_restaurant", "restaurant", "food" "establishment", "point_of_interest". Sử dụng includedTypes và excludedTypes để lọc kết quả trên danh sách các loại được liên kết với một địa điểm.

    Khi bạn chỉ định một loại chính chung, chẳng hạn như "restaurant" hoặc "hotel", câu trả lời có thể chứa các địa điểm có loại chính cụ thể hơn đồng hồ hẹn giờ được chỉ định. Ví dụ: bạn chỉ định bao gồm loại chính "restaurant". Sau đó, câu trả lời có thể chứa địa điểm có loại chính là "restaurant", nhưng câu trả lời cũng có thể chứa những địa điểm có từ khoá cụ thể hơn loại chính, chẳng hạn như "chinese_restaurant" hoặc "seafood_restaurant".

    Nếu nội dung tìm kiếm được chỉ định với hạn chế nhiều loại, thì chỉ địa điểm đáp ứng tất cả các hạn chế sẽ được trả về. Ví dụ: nếu bạn chỉ định {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, địa điểm được trả lại cung cấp "restaurant" dịch vụ liên quan nhưng không hoạt động chủ yếu dưới dạng "steak_house".

    includedTypes

    Danh sách các loại địa điểm từ Bảng A để tìm kiếm. Nếu tham số này bị bỏ qua, hàm sẽ trả về tất cả các loại địa điểm.

    excludedTypes

    Danh sách các loại địa điểm từ Bảng A để loại trừ khỏi tìm kiếm.

    Nếu bạn chỉ định cả includedTypes (chẳng hạn như "school") và excludedTypes (chẳng hạn như "primary_school") trong yêu cầu thì hàm này câu trả lời bao gồm các địa điểm được phân loại là "school" nhưng không phải là "primary_school". Câu trả lời bao gồm các địa điểm khớp với ít nhất một của includedTypes và không có mục nào trong số excludedTypes.

    Nếu có bất kỳ loại xung đột nào, chẳng hạn như một loại xuất hiện trong cả includedTypes và excludedTypes thì hệ thống sẽ trả về lỗi INVALID_REQUEST.

    includedPrimaryTypes

    Danh sách các loại địa điểm chính từ Bảng A cần bao gồm trong một tìm kiếm.

    excludedPrimaryTypes

    Danh sách các loại địa điểm chính từ Bảng A để loại trừ khỏi một lượt tìm kiếm.

    Nếu có bất kỳ loại chính nào xung đột với nhau, chẳng hạn như một loại xuất hiện trong cả hai includedPrimaryTypes và excludedPrimaryTypes, một thuộc tính Trả về lỗi INVALID_ARGUMENT.

  • maxResultCount

    Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Giá trị phải nằm trong khoảng 1 và 20 (mặc định).

  • rankPreference

    Loại thứ hạng sẽ sử dụng. Nếu tham số này bị bỏ qua, các kết quả được xếp hạng theo mức độ phổ biến. Có thể là một trong những trạng thái sau:

    • .popularity (mặc định) Sắp xếp kết quả dựa trên mức độ phổ biến.
    • .distance Sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí được chỉ định.

  • regionCode

    Mã vùng dùng để định dạng phản hồi, được chỉ định làm mã CLDR gồm hai ký tự. Không có giá trị mặc định.

    Nếu tên quốc gia của trường formattedAddress trong phản hồi khớp với regionCode, mã quốc gia bị bỏ khỏi formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress, tức là luôn bao gồm quốc gia tên hoặc trên shortFormattedAddress, mà không bao giờ có tên đó.

    Hầu hết mã CLDR đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "Vương quốc Anh và Bắc Ireland"). Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.

Hiển thị thuộc tính trong ứng dụng của bạn

Khi ứng dụng của bạn hiển thị thông tin thu được từ GMSPlacesClient! chẳng hạn như ảnh và bài đánh giá, thì ứng dụng cũng phải cho thấy các thông tin ghi nhận sự đóng góp cần thiết.

Ví dụ: thuộc tính reviews của đối tượng GMSPlacesClient chứa một mảng tối đa năm GMSPlaceReview . Mỗi đối tượng GMSPlaceReview có thể chứa thông tin ghi nhận sự đóng góp và thông tin ghi nhận tác giả. Nếu hiển thị bài đánh giá trong ứng dụng của mình, thì bạn cũng phải hiển thị mọi thuộc tính hoặc tác giả phân bổ giá trị đóng góp.

Để biết thêm thông tin, hãy xem tài liệu về phân bổ.