การค้นหาใกล้เคียง (ใหม่) คำขอใช้ประเภทสถานที่อย่างน้อย 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
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* ช่องplaces.name
มี ชื่อทรัพยากร สถานที่ ในแบบฟอร์ม: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
,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
เพื่อกรองผลลัพธ์ ประเภทหลักของสถานที่สถานที่แห่งหนึ่งสามารถมีค่าหลายค่าจากประเภทได้ ตาราง ก ที่เกี่ยวข้อง ตัวอย่างเช่น ร้านอาหารอาจมีประเภทต่อไปนี้
"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
รายการ -
languageCode
ภาษาที่จะแสดงผลการค้นหา
- ดูรายการภาษาที่รองรับ Google บ่อยๆ อัปเดตภาษาที่รองรับ ดังนั้นรายการนี้เป็นเพียงตัวอย่างบางส่วนเท่านั้น
- หากไม่ได้ระบุ
languageCode
ค่าเริ่มต้นของ API จะเป็นen
ถ้า คุณระบุรหัสภาษาที่ไม่ถูกต้อง API แสดงผลINVALID_ARGUMENT
- API พยายามอย่างสุดความสามารถเพื่อให้ที่อยู่ที่ทั้งผู้ใช้และผู้ใช้และ ท้องถิ่น เพื่อให้บรรลุเป้าหมายนี้ Google Analytics จะแสดงที่อยู่ในภาษาท้องถิ่น ทับศัพท์เป็นสคริปต์ที่ผู้ใช้สามารถอ่านได้หากจำเป็น โดยให้สังเกตตาม ภาษา ส่วนที่อยู่อื่นๆ ทั้งหมดจะส่งคืนในภาษาที่ต้องการ องค์ประกอบที่อยู่คือ ทั้งหมดจะแสดงผลในภาษาเดียวกัน ซึ่งได้รับเลือกจากคอมโพเนนต์แรก
- หากไม่มีชื่อในภาษาที่ต้องการ 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 ให้เลือกไอคอนขยาย
เพื่อขยายหน้าต่างโปรแกรมสำรวจ API