คำขอการค้นหาใกล้เคียง (ใหม่) จะป้อนภูมิภาคเพื่อค้นหาโดยระบุเป็นวงกลม ซึ่งระบุตามพิกัดละติจูดและลองจิจูดของจุดศูนย์กลางของวงกลมและรัศมีเป็นเมตร คำขอจะแสดงผลรายการสถานที่ที่ตรงกัน ซึ่งแต่ละรายการแสดงด้วยออบเจ็กต์ 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; } } ];
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 }
คำตอบสำหรับการค้นหาใกล้เคียง
Nearby Search API แสดงผลอาร์เรย์ที่ตรงกันในรูปแบบของออบเจ็กต์GMSPlace
โดยมีออบเจ็กต์ GMSPlace
1 รายการต่อตำแหน่งที่ตรงกัน
นอกจากช่องข้อมูลแล้ว ออบเจ็กต์ GMSPlace
ในการตอบสนองจะมีฟังก์ชันสมาชิกต่อไปนี้
-
isOpen
จะคำนวณว่าสถานที่เปิดในเวลาที่ระบุหรือไม่ isOpenAtDate
คำนวณว่าสถานที่เปิดในวันที่ระบุหรือไม่
พารามิเตอร์ที่จำเป็น
ใช้ออบเจ็กต์ GMSPlaceSearchNearbyRequest
เพื่อระบุพารามิเตอร์ที่จำเป็นสำหรับการค้นหา
-
รายการช่อง
เมื่อขอรายละเอียดสถานที่ คุณต้องระบุข้อมูลที่จะแสดงผลในออบเจ็กต์
GMSPlace
สำหรับสถานที่นั้นเป็นมาสก์ฟิลด์ หากต้องการกำหนดฟิลด์มาสก์ ให้ส่งอาร์เรย์ของค่าจากGMSPlaceProperty
ไปยังออบเจ็กต์GMSPlaceSearchNearbyRequest
การมาสก์ฟิลด์เป็นวิธีการออกแบบที่ดีที่จะไม่ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาในการประมวลผลและการเรียกเก็บเงินที่ไม่จําเป็นระบุช่องต่อไปนี้อย่างน้อย 1 ช่อง
ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (พื้นฐาน)
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyCoordinate
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyName
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlaceID
,GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ขั้นสูง):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ที่ต้องการ)
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];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
วัตถุ
GMSPlaceLocationRestriction
ที่กำหนดภูมิภาคในการค้นหาโดยระบุเป็นวงกลม กำหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 รัศมีเริ่มต้นคือ 0.0 คุณต้องตั้งค่าในคำขอให้มีค่ามากกว่า 0.0
พารามิเตอร์ที่ไม่บังคับ
ใช้ออบเจ็กต์ GMSPlaceSearchNearbyRequest
เพื่อระบุพารามิเตอร์ที่ไม่บังคับสำหรับการค้นหา
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
ช่วยให้คุณระบุประเภทจากประเภทตาราง ก ที่ใช้กรองผลการค้นหาได้ คุณระบุหมวดหมู่ข้อจำกัดได้สูงสุด 50 ประเภท
สถานที่จะมีประเภทหลักได้เพียงประเภทเดียวจากประเภทตาราง ก ที่เชื่อมโยงกับสถานที่ดังกล่าว ตัวอย่างเช่น ประเภทหลักอาจเป็น
"mexican_restaurant"
หรือ"steak_house"
ใช้includedPrimaryTypes
และexcludedPrimaryTypes
เพื่อกรองผลลัพธ์ในประเภทหลักของสถานที่สถานที่อาจมีค่าหลายประเภทจากประเภทตาราง ก ที่เชื่อมโยงกับสถานที่ดังกล่าวก็ได้ เช่น ร้านอาหารอาจมีประเภทต่อไปนี้
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
ใช้includedTypes
และexcludedTypes
เพื่อกรองผลลัพธ์ในรายการประเภทที่เชื่อมโยงกับสถานที่หากระบุการค้นหาโดยมีข้อจำกัดหลายประเภท ระบบจะแสดงผลเฉพาะสถานที่ที่ตรงกับข้อจำกัดทั้งหมดเท่านั้น ตัวอย่างเช่น หากคุณระบุ
{"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
แต่ละรายการอาจมีการระบุแหล่งที่มาและการระบุแหล่งที่มาผู้เขียน
หากแสดงรีวิวในแอป คุณก็ต้องแสดงการระบุแหล่งที่มาหรือการระบุแหล่งที่มาของผู้เขียนด้วย
สำหรับข้อมูลเพิ่มเติม ดูเอกสารเกี่ยวกับการระบุแหล่งที่มา