คำขอการค้นหาใกล้เคียง (ใหม่) จะใช้ประเภทสถานที่อย่างน้อย 1 ประเภท และแสดงผลรายการสถานที่ที่ตรงกันภายในพื้นที่ที่ระบุ ต้องมีฟิลด์มาสก์ที่ระบุประเภทข้อมูลอย่างน้อย 1 ประเภท การค้นหาใกล้เคียง (ใหม่) รองรับเฉพาะคำขอ POST เท่านั้น
API Explorer ช่วยให้คุณสามารถสร้างคำขอแบบเรียลไทม์เพื่อทำความคุ้นเคยกับ API และตัวเลือก API ดังนี้
ลองใช้งานคำขอการค้นหาใกล้เคียง (ใหม่)
คำขอการค้นหาใกล้เคียง (ใหม่) คือคำขอ HTTP POST ไปยัง URL ในแบบฟอร์ม
https://places.googleapis.com/v1/places:searchNearby
ส่งพารามิเตอร์ทั้งหมดในเนื้อหาคำขอ JSON หรือในส่วนหัวเป็นส่วนหนึ่งของคำขอ POST เช่น
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
การตอบกลับการค้นหาใกล้เคียง (ใหม่)
การค้นหาใกล้เคียง (ใหม่) จะแสดงผล ออบเจ็กต์ JSON เป็นการตอบกลับ คำตอบ:
- อาร์เรย์
places
มีตำแหน่งที่ตรงกันทั้งหมด - แต่ละตำแหน่งในอาร์เรย์จะแสดงด้วยออบเจ็กต์
Place
ออบเจ็กต์Place
มีข้อมูลโดยละเอียดเกี่ยวกับสถานที่เดียว - FieldMask ที่ส่งผ่านในคำขอจะระบุรายการของช่อง
ที่แสดงผลในออบเจ็กต์
Place
ออบเจ็กต์ JSON ที่ครบถ้วนอยู่ในรูปแบบต่อไปนี้
{ "places": [ { object (Place) } ] }
พารามิเตอร์ที่จำเป็น
-
FieldMask
ระบุรายการฟิลด์ที่จะแสดงผลในคำตอบด้วยการสร้างมาสก์ฟิลด์การตอบกลับ ส่งมาสก์ของช่องคำตอบไปยังเมธอดโดยใช้พารามิเตอร์ของ URL
$fields
หรือfields
หรือใช้ส่วนหัว HTTPX-Goog-FieldMask
ไม่มีรายการเริ่มต้นของฟิลด์ที่แสดงผลในคำตอบ หากคุณไม่ใส่ฟิลด์มาสก์ เมธอดจะแสดงข้อผิดพลาดการมาสก์ช่องเป็นแนวทางปฏิบัติในการออกแบบที่ดีเพื่อให้ไม่ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาในการประมวลผลและการเรียกเก็บเงินที่ไม่จําเป็น
ระบุรายการประเภทข้อมูลสถานที่ที่จะแสดงโดยคั่นด้วยคอมมา เช่น เพื่อดึงข้อมูลชื่อที่แสดงและที่อยู่ของสถานที่
X-Goog-FieldMask: places.displayName,places.formattedAddress
ใช้
*
เพื่อเรียกข้อมูลช่องทั้งหมดX-Goog-FieldMask: *
ระบุช่องต่อไปนี้อย่างน้อย 1 ช่อง
ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (พื้นฐาน):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
, {1/2} , , , {1/2} {1/2} {1/2}places.name
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
ใช้places.displayName
เพื่อเข้าถึงชื่อข้อความของสถานที่ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ขั้นสูง) ให้แสดงขึ้น
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ที่ต้องการ):
<br-ph - "ph - 2 - x" <br - 2 <br - "1 x x 2 x 2"><br - " TH <br - " <br - " ">
places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
พื้นที่ที่จะค้นหาระบุเป็นวงกลม กำหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 รัศมีเริ่มต้นคือ 0.0 คุณต้องตั้งค่าในคำขอเป็นค่าที่มากกว่า 0.0
ตัวอย่างเช่น
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
พารามิเตอร์ที่ไม่บังคับ
-
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
-
languageCode
ภาษาของผลการค้นหา
- ดูรายการภาษาที่รองรับ Google จะอัปเดตภาษาที่รองรับเป็นประจำ ดังนั้นรายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
- หากไม่ได้ให้
languageCode
ค่าเริ่มต้นของ API จะเป็นen
หากคุณระบุรหัสภาษาที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาดINVALID_ARGUMENT
- API จะดำเนินการอย่างเต็มที่เพื่อมอบที่อยู่ที่ทั้งผู้ใช้และคนในพื้นที่อ่านได้ เพื่อให้บรรลุเป้าหมายดังกล่าว เครื่องมือจะแสดงที่อยู่ในภาษาท้องถิ่นที่ทับศัพท์เป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น โดยสังเกตภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ ทั้งหมดจะแสดงผลในภาษาที่ต้องการ คอมโพเนนต์ที่อยู่ทั้งหมดจะแสดงเป็นภาษาเดียวกัน ซึ่งจะเลือกจากคอมโพเนนต์แรก
- หากไม่มีชื่อในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
- ภาษาที่ต้องการมีอิทธิพลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกที่จะแสดงผล และลำดับการแสดงผล โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะตีความตัวย่อต่างกันไปตามภาษา เช่น ตัวย่อของประเภทถนน หรือคำพ้องความหมายที่อาจใช้ได้ในภาษาหนึ่งแต่ไม่ถูกต้องในอีกภาษาหนึ่ง
-
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" (ทางเทคนิคสำหรับเอนทิตีของ "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ") พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง
ตัวอย่างการค้นหาใกล้เคียง (ใหม่)
ค้นหาสถานที่ประเภทเดียว
ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับชื่อที่แสดงของร้านอาหารทั้งหมดภายในรัศมี 500 เมตรซึ่งกำหนดโดย circle
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
โปรดทราบว่าส่วนหัว X-Goog-FieldMask
ระบุว่าการตอบกลับมีช่องข้อมูลต่อไปนี้ places.displayName
คำตอบจะอยู่ในรูปแบบดังนี้
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
เพิ่มประเภทข้อมูลเพิ่มเติมลงในมาสก์ของช่องเพื่อแสดงข้อมูลเพิ่มเติม
ตัวอย่างเช่น เพิ่ม places.formattedAddress,places.types,places.websiteUri
เพื่อใส่ที่อยู่ร้านอาหาร ประเภท และที่อยู่เว็บในการตอบกลับ
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
การตอบกลับจะอยู่ในแบบฟอร์มแล้ว
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
ค้นหาสถานที่ประเภทต่างๆ
ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับชื่อที่แสดงของร้านสะดวกซื้อและร้านขายสุราทั้งหมดภายในรัศมี 1,000 เมตรของ circle
ที่ระบุ
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyตัวอย่างนี้จะเพิ่ม
places.primaryType
และ places.types
ลงในมาสก์ของช่อง เพื่อให้คำตอบมีข้อมูลประเภทเกี่ยวกับสถานที่แต่ละแห่ง ซึ่งจะช่วยให้เลือกสถานที่ที่เหมาะสมจากผลลัพธ์ได้ง่ายขึ้น
ยกเว้นประเภทสถานที่ในการค้นหา
ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับสถานที่ทั้งหมดในประเภท "school"
ยกเว้นสถานที่ทั้งหมดในประเภท "primary_school"
และจัดอันดับผลการค้นหาตามระยะทาง
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
ค้นหาสถานที่ทั้งหมดใกล้พื้นที่โดยจัดอันดับตามระยะทาง
ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับสถานที่ที่ใกล้จุดหนึ่งๆ ในตัวเมืองซานฟรานซิสโก ในตัวอย่างนี้ คุณรวมพารามิเตอร์ rankPreference
เพื่อจัดอันดับผลลัพธ์ตามระยะทาง ดังนี้
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
ลองใช้เลย
โปรแกรมสำรวจ API ให้คุณสร้างคำขอตัวอย่างเพื่อทำความคุ้นเคยกับ API และตัวเลือก API
- เลือกไอคอน API ทางด้านขวาของหน้า
- (ไม่บังคับ) ขยายแสดงพารามิเตอร์มาตรฐานและตั้งค่าพารามิเตอร์
fields
เป็นฟิลด์มาสก์ - (ไม่บังคับ) แก้ไขเนื้อหาคำขอ
- เลือกปุ่มดำเนินการ ในป๊อปอัป ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ
ในแผง API Explorer ให้เลือกไอคอนขยาย เพื่อขยายหน้าต่าง API Explorer