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

เอกสารฉบับนี้อธิบายภาพรวมที่ชัดเจนเกี่ยวกับพารามิเตอร์ทั้งหมดภายใน Places Insights API เราจะอธิบายแต่ละหัวข้อโดยละเอียด พร้อมให้ข้อมูลเชิงลึก แนวทางปฏิบัติเพื่อช่วยให้คุณใช้เครื่องมือนี้ตามความต้องการเกี่ยวกับข้อมูลทางภูมิศาสตร์

Places Insights API ช่วยให้คุณสามารถทำงานสำคัญได้หลายอย่าง:

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

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

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

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

ข้อมูลเชิงลึก

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

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

หมายเหตุ: หากเลือกตัวเลือกนี้ Places Insights API จะแสดงรหัสสถานที่ เฉพาะเมื่อ count เท่ากับ 100 หรือน้อยกว่า

ตัวกรอง

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

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

ตัวกรองตำแหน่งมีประเภทใดประเภทหนึ่งต่อไปนี้

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

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

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

คุณสามารถกำหนดพื้นที่ของคุณเป็นภูมิภาคโดยใช้พารามิเตอร์ place ใช้รหัสสถานที่ ที่แสดงถึงพื้นที่ทางภูมิศาสตร์ (เช่น พื้นที่ซึ่งแสดงโดย รูปหลายเหลี่ยม) ตัวอย่างเช่น รหัสสถานที่ของเมืองแทมปา ฟลอริดา คือ places/ChIJ4dG5s4K3wogRY7SWr4kTX6c

ประเภทภูมิภาคที่ไม่รองรับ
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise

คุณสามารถใช้ฟิลด์ types จากการเรียก Geocoding API เพื่อระบุ สถานที่ตั้งหรือที่อยู่ที่เชื่อมโยงกับรหัสสถานที่ เช่น เมือง ย่านใกล้เคียง หรือประเทศ

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

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

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

"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 (ใหม่) ต้องมีประเภท included_types หรือ included_primary_types อย่างน้อย 1 รายการ รวมไว้ด้วย

  • included_types: รายการประเภทสถานที่ที่รวมไว้
  • excluded_types: รายการประเภทสถานที่ที่ยกเว้น
  • included_primary_types: รายการประเภทสถานที่หลักที่รวมอยู่
  • excluded_primary_types: รายการประเภทสถานที่หลักที่ยกเว้น

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

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

ตัวกรองสามรายการที่เหลือเป็นตัวเลือก:

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

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

กรองตามสถานะการดําเนินการ (เช่น ดําเนินการหรือชั่วคราว ปิดอยู่)

ระดับราคา

กรองตามระดับราคา (เช่น ฟรี ปานกลาง หรือแพง)

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

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

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