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

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

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

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

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

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

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

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

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

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

ตัวกรอง

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

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

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

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

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

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

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

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

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

  • establishment: มักบ่งบอกถึงสถานที่ที่ยังไม่ได้จัดหมวดหมู่
  • street_number: ระบุเลขที่ถนนที่แน่นอน
  • floor: ระบุชั้นของที่อยู่อาคาร
  • post_box: ระบุตู้ไปรษณีย์ที่เฉพาะเจาะจง
  • street_address: ระบุที่อยู่แบบละเอียด
  • room: ระบุห้องของที่อยู่อาคาร
  • intersection: บ่งบอกถึงทางแยกสำคัญ ซึ่งมักเป็นทางแยกของถนนสายหลัก 2 สาย
  • landmark: ระบุสถานที่ใกล้เคียงที่ใช้เป็นข้อมูลอ้างอิงเพื่อช่วยในการนําทาง
  • subpremise: ระบุเอนทิตีที่ระบุที่อยู่ได้ซึ่งอยู่ต่ำกว่าระดับสถานที่ตั้ง เช่น อพาร์ตเมนต์ ยูนิต หรือห้องชุด
  • sublocality_level_5: องค์ประกอบที่อยู่ระดับย่อยที่เฉพาะเจาะจงที่สุด ซึ่งมักแสดงถึงย่านเล็กๆ เขตย่อย หรือพื้นที่ขนาดเล็กมากภายในเมือง
พื้นที่ที่กำหนดเอง

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

คุณสามารถไปที่ 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 Insights API รองรับได้ที่ตาราง A ในส่วนประเภทสถานที่ของ Places API (ใหม่) คุณต้องระบุประเภท includedTypes หรือ includedPrimaryTypes อย่างน้อย 1 ประเภท

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

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

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

คุณจะใช้ตัวกรองต่อไปนี้หรือไม่ก็ได้

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

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

ตัวกรอง operatingStatus ช่วยให้คุณกรองตามสถานะการดําเนินงานได้ (เช่น ดําเนินการอยู่หรือปิดชั่วคราว) หากไม่ได้ตั้งค่าตัวกรอง operatingStatus ระบบจะรวมเฉพาะสถานที่ที่มีสถานะการทํางานเป็น OPERATING_STATUS_OPERATIONAL ไว้ในผลการค้นหา

ระดับราคา

ตัวกรอง price_levels ช่วยให้คุณกรองตามระดับราคาได้ (เช่น ฟรี ปานกลาง หรือแพง) หากไม่ได้ตั้งค่าตัวกรอง price_levels ระบบจะรวมระดับราคาทั้งหมดไว้ในผลลัพธ์

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

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

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

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