คำขอการค้นหาใกล้เคียง (ใหม่) จะใช้ประเภทสถานที่อย่างน้อย 1 ประเภท และแสดงผลรายการสถานที่ที่ตรงกันภายในพื้นที่ที่ระบุ ต้องระบุฟิลด์มาสก์ที่ระบุประเภทข้อมูลอย่างน้อย 1 ประเภท การค้นหาใกล้เคียง (ใหม่) รองรับเฉพาะคำขอ POST เท่านั้น
โปรแกรมสำรวจ API ช่วยให้คุณสร้างคำขอแบบเรียลไทม์ได้เพื่อทำความคุ้นเคยกับ 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.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
, {18/0}, {3/2}, {3/2}places.name
places.primaryTypeDisplayName
places.shortFormattedAddress
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 การค้นหาใกล้เคียง (ที่ต้องการ)
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
, {1/2}, {1/2}, {1/2},places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
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
ช่วยให้คุณระบุรายการประเภทจากประเภทตาราง A ที่ใช้ในการกรองผลการค้นหา หมวดหมู่ข้อจำกัดแต่ละประเภทระบุได้สูงสุด 50 ประเภท
สถานที่หนึ่งๆ มีประเภทหลักประเภทเดียวจากประเภทตาราง A ที่เชื่อมโยงกับสถานที่นั้นได้เท่านั้น เช่น ประเภทหลักอาจเป็น
"mexican_restaurant"
หรือ"steak_house"
ใช้includedPrimaryTypes
และexcludedPrimaryTypes
เพื่อกรองผลลัพธ์ตามประเภทหลักของสถานที่สถานที่อาจมีค่าหลายประเภทจากประเภทตาราง A ที่เชื่อมโยงอยู่ด้วย เช่น ร้านอาหารอาจมีประเภทต่อไปนี้
"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 Explorer ให้คุณสร้างคำขอตัวอย่างเพื่อทำความคุ้นเคยกับ API และตัวเลือก API
- เลือกไอคอน API ทางด้านขวาของหน้า
- (ไม่บังคับ) ขยายแสดงพารามิเตอร์มาตรฐาน และตั้งค่าพารามิเตอร์
fields
เป็นฟิลด์มาสก์ - แก้ไขเนื้อหาคำขอ (ไม่บังคับ)
- เลือกปุ่มดำเนินการ ในป๊อปอัป ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ
ในแผง API Explorer ให้เลือกไอคอนขยาย เพื่อขยายหน้าต่าง API Explorer