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

เอกสารนี้อธิบายพารามิเตอร์คำขอสำหรับ 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: รายการประเภทสถานที่หลักที่จะยกเว้น

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

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

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

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

• 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