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

เอกสารนี้อธิบายพารามิเตอร์คำขอสำหรับ 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: กำหนดพื้นที่เป็นรูปหลายเหลี่ยมที่กำหนดเอง

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

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

วงกลม

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

• center:
  • latLng: ละติจูดและลองจิจูดของจุดศูนย์กลางของวงกลม ละติจูดต้องเป็นตัวเลขระหว่าง -90 ถึง 90 ลองจิจูดต้องเป็นตัวเลขระหว่าง -180 ถึง 180 (รวม)
  • 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: รายการประเภทสถานที่หลักที่ยกเว้น

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

หมายเหตุ: ตัวกรองประเภทจะรวมประเภทย่อยของประเภทที่ระบุโดยอัตโนมัติ ตัวอย่างเช่น หากคุณกรองตาม gym ผลการค้นหาจะรวมสถานที่ที่จัดอยู่ในประเภทย่อยด้วย เช่น yoga_studio

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

ตัวกรองต่อไปนี้ไม่บังคับ

• operatingStatus: ระบุสถานะของสถานที่ที่จะรวมหรือยกเว้น ค่าเริ่มต้นคือการกรองตาม operatingStatus: OPERATING_STATUS_OPERATIONAL (ค่าที่เจาะจง 1 ค่า)
• 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