การค้นหาในบริเวณใกล้เคียง (ใหม่)

เลือกแพลตฟอร์ม: Android iOS JavaScript เว็บเซอร์วิส

คำขอการค้นหาใกล้เคียง (ใหม่) จะรับอินพุตเป็นภูมิภาคที่จะค้นหาซึ่งระบุเป็นวงกลม โดยกำหนดจากพิกัดละติจูดและลองจิจูดของจุดศูนย์กลางของวงกลมและรัศมีเป็นเมตร คำขอจะแสดงรายการสถานที่ที่ตรงกัน โดยแต่ละรายการจะแสดงด้วยออบเจ็กต์ GMSPlace ภายในพื้นที่การค้นหาที่ระบุ

โดยค่าเริ่มต้น การตอบกลับจะมีสถานที่ทุกประเภทภายในพื้นที่การค้นหา คุณกรองคำตอบได้โดยระบุรายการประเภทสถานที่ที่จะรวมหรือยกเว้นออกจากคำตอบอย่างชัดเจน เช่น คุณสามารถระบุให้รวมเฉพาะสถานที่ประเภท "ร้านอาหาร" "ร้านเบเกอรี่" และ "คาเฟ่" ไว้ในคำตอบ หรือยกเว้นสถานที่ประเภท "โรงเรียน" ทั้งหมด

คำขอการค้นหาในบริเวณใกล้เคียง (ใหม่)

ส่งคําขอการค้นหาใกล้เคียงโดยเรียกใช้ GMSPlacesClient searchNearbyWithRequest: โดยส่งผ่านออบเจ็กต์ GMSPlaceSearchNearbyRequest ที่กําหนดพารามิเตอร์คําขอและเมธอดการเรียกกลับซึ่งมีประเภทเป็น GMSPlaceSearchNearbyResultCallback เพื่อจัดการกับการตอบกลับ

ออบเจ็กต์ GMSPlaceSearchNearbyRequest จะระบุพารามิเตอร์ที่จําเป็นและไม่บังคับทั้งหมดสําหรับคําขอ พารามิเตอร์ที่จําเป็น ได้แก่

  • รายการช่องที่จะแสดงผลในออบเจ็กต์ GMSPlace หรือที่เรียกว่ามาสก์ฟิลด์ตามที่ระบุโดย GMSPlaceProperty หากคุณไม่ได้ระบุฟิลด์อย่างน้อย 1 ช่องในรายการฟิลด์ หรือไม่ได้ระบุรายการฟิลด์เลย การเรียกใช้จะแสดงข้อผิดพลาด
  • การจำกัดตำแหน่ง ซึ่งหมายถึงวงกลมที่กําหนดพื้นที่การค้นหา

ตัวอย่างคำขอค้นหาในพื้นที่นี้ระบุว่าออบเจ็กต์ GMSPlace ที่ตอบกลับต้องมีชื่อสถานที่ (GMSPlacePropertyName) และพิกัดสถานที่ (GMSPlacePropertyCoordinate) สำหรับออบเจ็กต์ GMSPlace แต่ละรายการในผลการค้นหา และยังกรองคำตอบให้แสดงเฉพาะสถานที่ประเภท "ร้านอาหาร" และ "คาเฟ่" เท่านั้น

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 สำหรับ iOS (เวอร์ชันตัวอย่าง)

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
}

การตอบกลับการค้นหาในพื้นที่ใกล้เคียง

Nearby Search API จะแสดงผลอาร์เรย์รายการที่ตรงกันในรูปแบบออบเจ็กต์ GMSPlace โดยจะมีออบเจ็กต์ GMSPlace 1 รายการต่อสถานที่ที่ตรงกัน

รับสถานะเปิด

ออบเจ็กต์ GMSPlacesClient มีฟังก์ชันสมาชิกชื่อ isOpenWithRequest (isOpenRequest ใน Swift และ isPlaceOpenRequest ใน GooglePlacesSwift) ซึ่งแสดงผลลัพธ์ที่ระบุว่าสถานที่เปิดอยู่หรือไม่ ณ เวลาที่มีการเรียกใช้

เมธอดนี้ใช้อาร์กิวเมนต์ประเภท GMSPlaceIsOpenWithRequest รายการเดียวที่มีข้อมูลต่อไปนี้

  • ออบเจ็กต์ GMSPlace หรือสตริงที่ระบุรหัสสถานที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างออบเจ็กต์สถานที่ซึ่งมีฟิลด์ที่จำเป็นได้ที่รายละเอียดสถานที่
  • ออบเจ็กต์ NSDate (Obj-C) หรือ Date (Swift) ไม่บังคับซึ่งระบุเวลาที่คุณต้องการตรวจสอบ หากไม่ได้ระบุเวลา ค่าเริ่มต้นจะเป็นปัจจุบัน
  • วิธีการ GMSPlaceOpenStatusResponseCallback ในการจัดการการตอบกลับ
    • >

เมธอด GMSPlaceIsOpenWithRequest กำหนดให้ต้องตั้งค่าฟิลด์ต่อไปนี้ในแออบเจ็กต์ GMSPlace

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

หากไม่ได้ระบุฟิลด์เหล่านี้ในออบเจ็กต์สถานที่ หรือหากคุณส่งรหัสสถานที่ เมธอดจะใช้ GMSPlacesClient GMSFetchPlaceRequest: เพื่อดึงข้อมูล

การตอบกลับ isOpenWithRequest รายการ

isOpenWithRequest จะแสดงผลออบเจ็กต์ GMSPlaceIsOpenResponse ที่มีค่าบูลีนชื่อ status ซึ่งระบุว่าธุรกิจเปิด ปิด หรือไม่ทราบสถานะ

ภาษา ค่าหากเปิด ค่าหากปิดอยู่ ค่าในกรณีที่ไม่ทราบสถานะ
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (เวอร์ชันตัวอย่าง) true false nil

การเรียกเก็บเงินสำหรับ isOpenWithRequest

  • ระบบจะเรียกเก็บเงินสำหรับช่อง GMSPlacePropertyUTCOffsetMinutes และ GMSPlacePropertyBusinessStatus ภายใต้ SKU ข้อมูลพื้นฐาน ระบบจะเรียกเก็บเงินสำหรับเวลาเปิดทำการที่เหลือภายใต้ SKU รายละเอียดสถานที่สำหรับ Enterprise
  • หากออบเจ็กต์ GMSPlace มีช่องเหล่านี้อยู่แล้วจากคำขอก่อนหน้า ระบบจะไม่เรียกเก็บเงินจากคุณอีก

ตัวอย่าง: ส่งคำขอ GMSPlaceIsOpenWithRequest

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มต้น GMSPlaceIsOpenWithRequest ภายในออบเจ็กต์ GMSPlace ที่มีอยู่

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
          }

พารามิเตอร์ที่จำเป็น

ใช้ออบเจ็กต์ GMSPlaceSearchNearbyRequest เพื่อระบุพารามิเตอร์ที่จําเป็นสําหรับการค้นหา

  • รายการช่อง

    เมื่อขอรายละเอียดสถานที่ คุณต้องระบุข้อมูลที่จะให้แสดงในออบเจ็กต์ GMSPlace สำหรับสถานที่เป็นมาสก์ฟิลด์ หากต้องการกำหนดมาสก์ช่อง ให้ส่งอาร์เรย์ของค่าจาก GMSPlaceProperty ไปยังออบเจ็กต์ GMSPlaceSearchNearbyRequest การมาสก์ฟิลด์เป็นแนวทางปฏิบัติด้านการออกแบบที่ดีเพื่อให้มั่นใจว่าคุณจะไม่ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาในการประมวลผลและการเรียกเก็บเงินที่ไม่จำเป็น

    ระบุฟิลด์ต่อไปนี้อย่างน้อย 1 ฟิลด์

    • ฟิลด์ต่อไปนี้จะทริกเกอร์SKU ของ Nearby Search Pro

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

    • ฟิลด์ต่อไปนี้จะทริกเกอร์SKU ของ Nearby Search Enterprise

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • ช่องต่อไปนี้จะทริกเกอร์SKU ของ Search ในพื้นที่ของ Enterprise Plus

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

    ตัวอย่างต่อไปนี้ส่งรายการค่าช่อง 2 รายการเพื่อระบุว่าออบเจ็กต์ GMSPlace ที่คำขอแสดงผลมีช่อง name และ 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 สำหรับ iOS (เวอร์ชันตัวอย่าง)

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

  • locationRestriction

    ออบเจ็กต์ GMSPlaceLocationRestriction ที่กําหนดขอบเขตการค้นหาที่ระบุเป็นวงกลม โดยกําหนดด้วยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 เท่านั้น รัศมีเริ่มต้นคือ 0.0 คุณต้องตั้งค่าในคำขอเป็นค่าที่มากกว่า 0.0

พารามิเตอร์ที่ไม่บังคับ

ใช้ออบเจ็กต์ GMSPlaceSearchNearbyRequest เพื่อระบุพารามิเตอร์ที่ไม่บังคับสําหรับการค้นหา

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    ให้คุณระบุรายการประเภทจากประเภทในตาราง ก ที่ใช้กรองผลการค้นหา ระบุประเภทได้สูงสุด 50 ประเภทในแต่ละหมวดหมู่ข้อจำกัดประเภท

    สถานที่มีประเภทหลักได้เพียงประเภทเดียวจากประเภทต่างๆ ของตาราง กที่เชื่อมโยงกับสถานที่นั้น เช่น ประเภทหลักอาจเป็น "mexican_restaurant" หรือ "steak_house" ใช้ includedPrimaryTypes และ excludedPrimaryTypes เพื่อกรองผลลัพธ์ตามประเภทหลักของสถานที่

    สถานที่หนึ่งๆ อาจมีค่าประเภทหลายค่าจากประเภทต่างๆ ที่เชื่อมโยงกับ Table A เช่น ร้านอาหารอาจมีประเภทต่อไปนี้ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ใช้ includedTypes และ excludedTypes เพื่อกรองผลการค้นหาในรายการประเภทที่เชื่อมโยงกับสถานที่

    เมื่อคุณระบุประเภทหลักทั่วไป เช่น "restaurant" หรือ "hotel" การตอบกลับอาจมีสถานที่ที่มีประเภทหลักที่เฉพาะเจาะจงกว่าประเภทที่ระบุ เช่น คุณระบุให้รวมประเภทหลักของ "restaurant" จากนั้นการตอบกลับอาจมีสถานที่ประเภทหลักเป็น "restaurant" แต่การตอบกลับอาจมีสถานที่ประเภทหลักที่เฉพาะเจาะจงมากขึ้น เช่น "chinese_restaurant" หรือ "seafood_restaurant" ได้ด้วย

    หากระบุการค้นหาด้วยข้อจำกัดหลายประเภท ระบบจะแสดงเฉพาะสถานที่ที่ตรงกับข้อจำกัดทั้งหมด ตัวอย่างเช่น หากคุณระบุ {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} สถานที่ที่แสดงผลจะให้บริการที่เกี่ยวข้องกับ "restaurant" แต่ไม่ได้ดำเนินการเป็น "steak_house" เป็นหลัก

    includedTypes

    รายการประเภทสถานที่จากตาราง กที่จะค้นหา หากไม่ระบุพารามิเตอร์นี้ ระบบจะแสดงสถานที่ทุกประเภท

    excludedTypes

    รายการประเภทสถานที่จากตาราง กที่จะยกเว้นจากการค้นหา

    หากคุณระบุทั้ง includedTypes (เช่น "school") และ excludedTypes (เช่น "primary_school") ในคำขอ การตอบกลับจะรวมสถานที่ที่จัดอยู่ในหมวดหมู่ "school" แต่ไม่ได้จัดอยู่ในหมวดหมู่ "primary_school" การตอบกลับจะมีสถานที่ที่ตรงกับ includedTypes อย่างน้อย 1 แห่ง และไม่มี excludedTypes

    หากมีประเภทที่ขัดแย้งกัน เช่น ประเภทที่ปรากฏทั้งใน includedTypes และ excludedTypes ระบบจะแสดงข้อผิดพลาด INVALID_REQUEST

    includedPrimaryTypes

    รายการประเภทสถานที่หลักจากตาราง กที่จะรวมในการค้นหา

    excludedPrimaryTypes

    รายการประเภทสถานที่หลักจากตาราง กที่จะยกเว้นจากการค้นหา

    หากมีประเภทหลักที่ขัดแย้งกัน เช่น ประเภทที่ปรากฏทั้งใน includedPrimaryTypes และ excludedPrimaryTypes ระบบจะแสดงข้อผิดพลาด INVALID_ARGUMENT

  • maxResultCount

    ระบุจำนวนผลลัพธ์สถานที่สูงสุดที่จะแสดง ต้องอยู่ระหว่าง 1 ถึง 20 (ค่าเริ่มต้น) เท่านั้น

  • rankPreference

    ประเภทการจัดอันดับที่จะใช้ หากไม่ระบุพารามิเตอร์นี้ ระบบจะจัดอันดับผลการค้นหาตามความนิยม อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

    • .popularity (ค่าเริ่มต้น) จัดเรียงผลการค้นหาตามความนิยม
    • .distance จัดเรียงผลลัพธ์จากน้อยไปมากตามระยะทางจากสถานที่ที่ระบุ

  • regionCode

    รหัสภูมิภาคที่ใช้จัดรูปแบบการตอบกลับ ซึ่งระบุเป็นค่า รหัส CLDR 2 อักขระ ไม่มีค่าเริ่มต้น

    หากชื่อประเทศของช่อง formattedAddress ในการตอบกลับตรงกับ regionCode ระบบจะไม่ใส่รหัสประเทศใน formattedAddress พารามิเตอร์นี้ไม่มีผลกับ adrFormatAddress ซึ่งรวมชื่อประเทศไว้เสมอ หรือกับ shortFormattedAddress ซึ่งไม่มีชื่อประเทศ

    รหัส CLDR ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นบางประการ ตัวอย่างเช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ส่วนรหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคสำหรับนิติบุคคล "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ") พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง

แสดงการระบุแหล่งที่มาในแอป

เมื่อแอปแสดงข้อมูลที่ได้จาก GMSPlacesClient เช่น รูปภาพและรีวิว แอปจะต้องแสดงการระบุแหล่งที่มาที่จําเป็นด้วย

เช่น พร็อพเพอร์ตี้ reviews ของออบเจ็กต์ GMSPlacesClient มีอาร์เรย์ออบเจ็กต์ GMSPlaceReview ไม่เกิน 5 รายการ ออบเจ็กต์ GMSPlaceReview แต่ละรายการอาจมีการระบุแหล่งที่มาและการระบุแหล่งที่มาของผู้เขียน หากแสดงรีวิวในแอป คุณต้องแสดงการระบุแหล่งที่มาหรือการระบุแหล่งที่มาของผู้เขียนด้วย

ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบเกี่ยวกับการระบุแหล่งที่มา