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

เลือกแพลตฟอร์ม: Android iOS JavaScript Web Service
นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (EEA)

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

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

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

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

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

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

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

Places Swift SDK

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
}

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

การตอบกลับการค้นหาในบริเวณใกล้เคียง

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

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

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

เมธอดนี้รับอาร์กิวเมนต์เดียวประเภท GMSPlaceIsOpenWithRequest ซึ่งมีข้อมูลต่อไปนี้

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

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

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

ภาษา มูลค่าหากเปิด มูลค่าหากปิด ค่าหากไม่ทราบสถานะ
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

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

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

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

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

Places Swift SDK

        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
        }

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

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

ใช้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 Nearby Search Enterprise Plus

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

    ตัวอย่างต่อไปนี้ส่งรายการค่าฟิลด์ 2 รายการ เพื่อระบุว่าออบเจ็กต์ GMSPlace ที่คำขอส่งคืนมีฟิลด์ name และ placeID

    Places Swift SDK

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

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

  • locationRestriction

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

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

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

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

    สถานที่อาจมีค่าประเภทหลายค่าจากประเภท ตาราง ก ที่เชื่อมโยงอยู่ด้วย เช่น ร้านอาหารอาจมีประเภทต่อไปนี้ "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" การตอบกลับจะรวมสถานที่ที่ตรงกับอย่างน้อย 1 รายการใน includedTypes และไม่มีรายการใดใน 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 แต่ละรายการอาจมีการระบุแหล่งที่มาและการระบุแหล่งที่มาของผู้เขียน หากแสดงรีวิวในแอป คุณต้องแสดงการระบุแหล่งที่มาหรือการระบุแหล่งที่มาของผู้เขียนด้วย

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