พารามิเตอร์คำขอ

เอกสารนี้อธิบายพารามิเตอร์คำขอสำหรับ Places Aggregate API รวมถึงข้อมูลเชิงลึกและแนวทางปฏิบัติแนะนำสำหรับการใช้บริการนี้

Places Aggregate API ช่วยให้คุณทำฟังก์ชันหลักๆ ได้หลายอย่าง ดังนี้

• นับสถานที่: ระบุจำนวนสถานที่ที่ตรงกับเกณฑ์ที่เฉพาะเจาะจง เช่น ประเภทสถานที่ สถานะการดำเนินงาน ระดับราคา และการให้คะแนน
• ดึงรายละเอียดสถานที่: รับชื่อสถานที่ที่ตรงกับตัวกรองที่ระบุ จากนั้นดึงข้อมูลโดยละเอียดเพิ่มเติมโดยใช้ Places API
• การกรองที่ยืดหยุ่น: ใช้ตัวกรองที่ครอบคลุมเพื่อให้ได้ข้อมูลรวมที่แม่นยำ ตัวกรองที่พร้อมใช้งาน ได้แก่
  • พื้นที่ทางภูมิศาสตร์ (วงกลม ภูมิภาค หรือรูปหลายเหลี่ยมที่กำหนดเอง)
  • ประเภทสถานที่
  • สถานะการดำเนินการ
  • ระดับราคา
  • ช่วงการจัดประเภท

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

ส่วนนี้ครอบคลุมพารามิเตอร์ที่จำเป็นเมื่อส่งคำขอไปยัง Places Aggregate API คำขอแต่ละรายการต้องระบุข้อมูลต่อไปนี้

• ประเภทข้อมูลเชิงลึก
• ตัวกรองตำแหน่งและตัวกรองประเภท

ประเภทข้อมูลเชิงลึก

ระบุประเภทข้อมูลเชิงลึกที่ต้องการคำนวณ ระบบรองรับข้อมูลเชิงลึกประเภทต่อไปนี้

• INSIGHT_COUNT: แสดงผลจำนวนสถานที่ที่ตรงกับเกณฑ์ตัวกรอง
• INSIGHT_PLACES: แสดงผลรหัสสถานที่ที่ตรงกับเกณฑ์ตัวกรอง

หมายเหตุ: หากเลือก INSIGHT_PLACES Places Aggregate API จะแสดงรหัสสถานที่ ก็ต่อเมื่อ count ไม่เกิน 100

ตัวกรอง

ระบุเกณฑ์สำหรับการกรองสถานที่ คุณต้องระบุ LocationFilter และ TypeFilter อย่างน้อย

กรองสถานที่ตั้ง

ตัวกรองสถานที่ตั้งอาจมีประเภทใดประเภทหนึ่งต่อไปนี้

• circle: กำหนดพื้นที่เป็นวงกลมที่มีจุดศูนย์กลางและรัศมี
• region: กำหนดพื้นที่เป็นภูมิภาค
• customArea: กำหนดพื้นที่เป็นรูปหลายเหลี่ยมที่กำหนดเอง

สำคัญ: พื้นที่สำหรับฟิลเตอร์ตำแหน่งต้องอยู่ระหว่าง 1556.86 ตารางเมตร (ประมาณขนาดของบล็อกในเมืองเล็กๆ) ถึง 2 ล้านล้านตารางเมตร (ประมาณขนาดของรัฐอลาสก้า) คำขอที่มีพื้นที่อยู่นอกช่วงนี้จะแสดงINVALID_ARGUMENTข้อผิดพลาด

หมายเหตุ: สำหรับเอนทิตีที่มีขอบเขตเป็นรูปหลายเหลี่ยมที่กำหนด เช่น สวนสาธารณะหรือสนามบิน ระบบจะถือว่าเอนทิตีนั้นอยู่ภายในพื้นที่ค้นหาหากส่วนใดส่วนหนึ่งของรูปหลายเหลี่ยม ตัดกับพื้นที่ค้นหาที่กำหนด (วงกลม ภูมิภาค หรือรูปหลายเหลี่ยมที่กำหนดเอง) จุดกึ่งกลางของเอนทิตีไม่จำเป็นต้องอยู่ภายในพื้นที่ค้นหา

วงกลม

หากเลือกพื้นที่ทางภูมิศาสตร์เป็นวงกลม คุณจะต้องระบุcenter และradius center อาจเป็นละติจูดและลองจิจูด หรือ รหัสสถานที่ของจุดศูนย์กลางของวงกลม วิธีนี้ช่วยให้กรองได้อย่างแม่นยำและถูกต้องตามภูมิภาควงกลมที่คุณกำหนด

• center:
  • latLng: ละติจูดและลองจิจูดของจุดศูนย์กลางของวงกลม ละติจูด ต้องเป็นตัวเลขระหว่าง -90 ถึง 90 (รวม 2 ตัวเลขนี้ด้วย) ลองจิจูดต้องเป็นตัวเลข ระหว่าง -180 ถึง 180 (รวม 2 ตัวเลขนี้ด้วย)
  • place: รหัสสถานที่ของจุดศูนย์กลางของวงกลม โปรดทราบว่าระบบรองรับเฉพาะจุด เท่านั้น สตริงนี้ต้องขึ้นต้นด้วยคำนำหน้า places/
• radius: รัศมีของวงกลมเป็นเมตร ตัวเลขนี้ต้องเป็นค่าบวก

ภูมิภาค

กำหนดพื้นที่เป็นภูมิภาคโดยส่งรหัสสถานที่ไปยังพารามิเตอร์ place รหัสสถานที่แสดงถึงพื้นที่ทางภูมิศาสตร์ (เช่น พื้นที่ที่แสดงด้วยรูปหลายเหลี่ยม) ตัวอย่างเช่น รหัสสถานที่ของแทมปา ฟลอริดา คือ places/ChIJ4dG5s4K3wogRY7SWr4kTX6c โปรดทราบว่ารหัสสถานที่บางรายการไม่มี เรขาคณิตที่กำหนดไว้อย่างชัดเจน และในกรณีเหล่านี้ Places Aggregate API จะแสดงรหัสข้อผิดพลาด 400 พร้อมข้อความที่ระบุว่าไม่รองรับภูมิภาค นอกจากนี้ สําหรับพื้นที่ทางภูมิศาสตร์ที่ซับซ้อน การเพิ่มประสิทธิภาพการประมวลผลภายในอาจทําให้ เกิดการประมาณพื้นที่มากเกินไปเล็กน้อย (สูงสุด 2-3%) ซึ่งแสดงถึง ภูมิภาค

สำคัญ: เมื่อใช้ตัวกรอง region กับ ประเภทข้อมูลเชิงลึก INSIGHT_PLACES ระบบจะปฏิเสธคำขอที่มีพื้นที่ ที่พิพาทโดยอัตโนมัติเพื่อให้มั่นใจในความถูกต้องและความเป็นกลางของ บริการของ Google พื้นที่ที่มีข้อพิพาทคือภูมิภาคที่มีขอบเขตขัดแย้งกันหรือมีการอ้างสิทธิ์ในดินแดนโดยประเทศหรือหน่วยงานต่างๆ พรมแดนที่มีการโต้แย้งจะแสดงเป็นเส้นประสีเทาใน Google Maps

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีระบุภูมิภาคที่มีการโต้แย้งได้ที่ ทำความเข้าใจชื่อและเส้นขอบชายแดนประเทศ

สำคัญ: Google ไม่รองรับรหัสสถานที่บางรายการที่อยู่ในประเภทภูมิภาคต่อไปนี้

• ประเภทภูมิภาคที่มีขนาดใหญ่มากจนทำให้เกิดเวลาในการตอบสนองสูง
• ประเภทภูมิภาคที่มีขนาดเล็กมากจนกระทบต่อการปฏิบัติตามข้อกำหนดด้านความเป็นส่วนตัว

หากต้องการตรวจสอบว่ารหัสสถานที่แสดงถึงประเภทสถานที่ที่ไม่รองรับหรือไม่ ให้ส่งรหัสสถานที่ในคำขอ Geocoding API การตอบกลับจะมีอาร์เรย์ type ซึ่งแสดงประเภทสถานที่ที่เชื่อมโยงกับรหัสสถานที่ เช่น locality neighborhood หรือ country ระบบจะปฏิเสธสถานที่สำหรับการกรองตามภูมิภาคหากประเภทใดประเภทหนึ่งตรงกับรายการนี้

ประเภทสถานที่ที่ไม่รองรับ ได้แก่

• establishment: โดยปกติจะระบุสถานที่ที่ยังไม่ได้จัดหมวดหมู่
• intersection: แสดงทางแยกหลัก ซึ่งมักจะเป็นทางแยกของถนนสายหลัก 2 สาย
• subpremise: ระบุเอนทิตีที่ระบุได้ซึ่งอยู่ต่ำกว่าระดับสถานที่ เช่น อพาร์ตเมนต์ ยูนิต หรือชุด

หมายเหตุ: แม้ว่าสถานที่บางแห่งจะไม่ได้อยู่ในรายการด้านบน แต่อาจถูกปฏิเสธหากไม่มีรูปเรขาคณิตแบบหลายเหลี่ยมที่กำหนดไว้อย่างชัดเจน ซึ่งมักเกิดขึ้นกับประเภทต่างๆ เช่น neighborhood, locality, sublocality และตัวแปรที่มีหมายเลข (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4) ในกรณีนี้ ระบบจะแสดงรหัสข้อผิดพลาด 400

พื้นที่ที่กำหนดเอง

กำหนดพื้นที่ของรูปหลายเหลี่ยมที่กำหนดเองโดยใช้พิกัดละติจูดและลองจิจูด

สำคัญ: พิกัดที่กำหนดจุดยอดของรูปหลายเหลี่ยมต้องแสดงตามลำดับทวนเข็มนาฬิกา ซึ่งเป็นไปตามธรรมเนียมมาตรฐานอุตสาหกรรมสำหรับ การกำหนดรูปหลายเหลี่ยม โดยลำดับทวนเข็มนาฬิกาจะระบุว่าด้านในของ รูปหลายเหลี่ยมอยู่ทางด้านซ้ายของขอบเขต

สำคัญ: พื้นที่ที่กำหนดเองต้องมีจุดยอดไม่เกิน 7, 000 จุด

คุณไปที่ https://geojson.io/ เพื่อ วาดรูปหลายเหลี่ยมที่กำหนดเองและป้อนพิกัดเหล่านั้นลงในคำขอได้ รูปหลายเหลี่ยมต้องมีพิกัดอย่างน้อย 4 รายการ โดยพิกัดแรกและพิกัดสุดท้าย ต้องเหมือนกัน พิกัดที่ระบุต้องไม่ซ้ำกันอย่างน้อย 3 รายการ

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

นอกจากนี้ ไม่อนุญาตให้ขอบที่ไม่อยู่ติดกันตัดกัน และไม่อนุญาตให้ใช้ขอบที่มี ความยาว 180 องศา (กล่าวคือ จุดยอดที่อยู่ติดกันต้องไม่อยู่ตรงข้ามกัน)

เช่น

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

ตัวกรองประเภท

ระบุประเภทสถานที่ที่จะรวมหรือยกเว้น ดูรายการประเภทสถานที่หลัก และรองที่ Places Aggregate API รองรับได้ที่ตาราง กในส่วนประเภทสถานที่สำหรับ Places API (ใหม่) คุณต้องระบุประเภท includedTypes หรือ includedPrimaryTypes อย่างน้อย 1 ประเภท

• includedTypes: รายการประเภทสถานที่ที่รวมไว้
• excludedTypes: รายการประเภทสถานที่ที่ยกเว้น
• includedPrimaryTypes: รายการประเภทสถานที่หลักที่รวมไว้
• excludedPrimaryTypes: รายการประเภทสถานที่หลักที่ยกเว้น

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ตัวกรองประเภทและประเภทสถานที่ทํางานได้ที่ข้อมูลเพิ่มเติมเกี่ยวกับตัวกรองประเภท

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

ตัวกรองต่อไปนี้เป็นตัวเลือกที่ไม่บังคับ

• operatingStatus: ระบุสถานะของสถานที่ที่จะรวมไว้หรือยกเว้น ค่าเริ่มต้นคือการกรองตาม operatingStatus: OPERATING_STATUS_OPERATIONAL (ค่าใดค่าหนึ่ง)
• priceLevels: ระดับราคาของสถานที่ที่จะรวม โดยค่าเริ่มต้น จะไม่มีการกรองระดับราคา และระบบจะแสดงสถานที่ทั้งหมด (รวมถึงสถานที่ที่ไม่มี ข้อมูลระดับราคา)
• ratingFilter: ระบุช่วงคะแนนของสถานที่ ค่าเริ่มต้นคือไม่มีการกรอง (การจัดประเภททั้งหมดจะรวมอยู่ในผลลัพธ์)

สถานะการดำเนินการ

operatingStatus ตัวกรองช่วยให้คุณกรองตามสถานะการทำงาน เช่น OPERATIONAL หรือ TEMPORARILY_CLOSED ได้ operatingStatusลักษณะการทำงานของตัวกรอง มีดังนี้

• หากไม่ได้ระบุตัวกรอง ระบบจะรวมเฉพาะสถานที่ที่มีสถานะการดำเนินงานเป็น OPERATING_STATUS_OPERATIONAL ไว้ในผลลัพธ์
• หากระบุตัวกรองอย่างน้อย 1 รายการ คุณต้องระบุค่าสถานะการทำงานที่ถูกต้อง (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED หรือ OPERATING_STATUS_TEMPORARILY_CLOSED)

ระดับราคา

priceLevelsตัวกรองช่วยให้คุณกรองสถานที่ตามระดับราคาได้ ค่าระดับราคาที่ถูกต้องคือ PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE และ PRICE_LEVEL_VERY_EXPENSIVE

ลักษณะการทำงานของตัวกรอง priceLevels มีดังนี้

• หากไม่ได้ระบุตัวกรอง: ระบบจะแสดงสถานที่ทั้งหมด ไม่ว่าจะมีระดับราคาที่กำหนดไว้หรือไม่ก็ตาม ซึ่งรวมถึงสถานที่ที่ไม่มีข้อมูลระดับราคา ซึ่งอาจไม่แสดงเมื่อกรองตามระดับราคาที่เฉพาะเจาะจง
• หากระบุตัวกรองอย่างน้อย 1 รายการ ระบบจะแสดงเฉพาะสถานที่ที่ตรงกับระดับราคาที่ระบุ

ตัวกรองคะแนน

กรองสถานที่ตามคะแนนเฉลี่ยที่ผู้ใช้ให้ ทั้ง 2 ฟิลด์นี้เป็นฟิลด์ ที่ไม่บังคับ ดังนั้นหากละเว้นไว้ ระบบจะตั้งค่าเริ่มต้นให้รวมสถานที่ ที่ไม่มีคะแนนด้วย

• minRating: การให้คะแนนของผู้ใช้โดยเฉลี่ยขั้นต่ำ (ระหว่าง 1.0 ถึง 5.0)
• maxRating: การให้คะแนนของผู้ใช้โดยเฉลี่ยสูงสุด (ระหว่าง 1.0 ถึง 5.0)

นอกจากนี้ ค่า minRating ต้องน้อยกว่าหรือเท่ากับค่า maxRating เสมอ หากระบุ minRating มากกว่า maxRating ระบบจะแสดงข้อผิดพลาด INVALID_ARGUMENT