Tham số yêu cầu

Tài liệu này cung cấp thông tin tổng quan rõ ràng về tất cả các thông số trong API Thông tin chi tiết về địa điểm. Chúng tôi sẽ đề cập chi tiết đến từng nhóm, cung cấp thông tin chi tiết và hiệu quả nhất để giúp bạn sử dụng công cụ này khi cần dữ liệu địa lý.

Places Insights API cho phép bạn thực hiện một số chức năng chính:

  • Đếm địa điểm: Xác định số lượng địa điểm phù hợp với tiêu chí, chẳng hạn như loại vị trí, trạng thái hoạt động, mức giá và điểm xếp hạng.
  • Truy xuất thông tin chi tiết về địa điểm: Lấy tên của địa điểm đáp ứng bộ lọc cụ thể, sau đó tìm nạp thêm thông tin chi tiết bằng cách sử dụng Places API.
  • Lọc linh hoạt: Áp dụng các bộ lọc toàn diện để nhận thông tin chi tiết chính xác. Các bộ lọc có thể sử dụng bao gồm:
    • Khu vực địa lý (hình tròn, khu vực hoặc đa giác tuỳ chỉnh)
    • Loại địa điểm
    • Trạng thái hoạt động
    • Các mức giá
    • Phạm vi xếp hạng

Thông số bắt buộc

Phần này đề cập đến các tham số bắt buộc khi gửi yêu cầu đến API Thông tin chi tiết về địa điểm. Mỗi yêu cầu phải cung cấp các thông tin sau:

  • Một loại thông tin chi tiết.
  • Bộ lọc vị trí và loại bộ lọc.

Thông tin chi tiết

Chỉ định loại thông tin chi tiết mà bạn muốn tính toán. Các loại thông tin chi tiết sau đây được hỗ trợ:

  • INSIGHT_COUNT: Trả về số lượng vị trí phù hợp với tiêu chí lọc.
  • INSIGHT_PLACES: Trả về mã địa điểm khớp với tiêu chí lọc.

Lưu ý: Nếu bạn chọn tuỳ chọn này, Places Insights API sẽ trả về mã địa điểm chỉ khi count từ 100 trở xuống.

Lọc

Chỉ định tiêu chí để lọc địa điểm. Ít nhất, bạn phải chỉ định LocationFilter và TypeFilter.

Bộ lọc vị trí

Bộ lọc vị trí có thể có một trong các loại sau:

  • circle: Xác định một diện tích là một hình tròn có tâm và bán kính.
  • region: Xác định một khu vực là một khu vực.
  • custom_area: Xác định một khu vực dưới dạng đa giác tuỳ chỉnh.
Hình tròn

Nếu chọn khu vực địa lý dưới dạng vòng tròn, bạn cần cung cấp center và radius. Trung tâm có thể là vĩ độ và kinh độ hoặc địa điểm Mã nhận dạng tâm đường tròn.

  • giữa:
    • lat_lng: Vĩ độ và kinh độ tại tâm vòng tròn. Vĩ độ phải là một số từ -90 đến 90, gồm cả hai giá trị này. Kinh độ phải ở dạng một số trong khoảng từ -180 đến 180.
    • place: Mã địa điểm của tâm vòng tròn. Lưu ý rằng chỉ điểm địa điểm được hỗ trợ. Chuỗi này phải bắt đầu bằng tiền tố places/.
  • radius: Bán kính của vòng tròn tính bằng mét. Đây phải là số dương.
Khu vực

Bạn có thể xác định khu vực của mình là một khu vực bằng cách dùng tham số place. Sử dụng mã địa điểm đại diện cho một khu vực địa lý (chẳng hạn như khu vực có thể biểu thị bằng đa giác). Ví dụ: Mã địa điểm của Nadia, FL là places/ChIJ4dG5s4K3wogRY7SWr4kTX6c.

Các loại khu vực không được hỗ trợ
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

Bạn có thể sử dụng trường types từ lệnh gọi API mã hoá địa lý để xác định loại vị trí hoặc địa chỉ được liên kết với một mã địa điểm, chẳng hạn như việc đó có phải là một thành phố, vùng lân cận hoặc quốc gia.

Khu vực tuỳ chỉnh

Xác định diện tích của đa giác tuỳ chỉnh bằng cách sử dụng toạ độ.

Bạn có thể truy cập vào https://geojson.io/ để vẽ một đa giác tuỳ chỉnh và hãy nhập các toạ độ đó vào yêu cầu. Một đa giác phải có ít nhất 4 toạ độ đầu tiên và toạ độ cuối cùng giống hệt nhau. Bên cạnh toạ độ đầu tiên và toạ độ cuối cùng, không được có toạ độ nào khác. Ví dụ:

"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
   }
]

Bộ lọc loại

Chỉ định các loại địa điểm để bao gồm hoặc loại trừ. Để có danh sách cả và các loại địa điểm phụ mà API Thông tin chi tiết về địa điểm hỗ trợ, hãy tham khảo Bảng A trong hướng dẫn về Loại địa điểm dành cho API Địa điểm (Mới). Phải có ít nhất một loại included_types hoặc included_primary_types bao gồm.

  • included_types: Danh sách các loại địa điểm đã bao gồm.
  • excluded_types: Danh sách các loại địa điểm bị loại trừ.
  • included_primary_types: Danh sách các loại địa điểm chính được thêm vào.
  • excluded_primary_types: Danh sách các loại địa điểm chính bị loại trừ.

Để tìm hiểu thêm về cách hoạt động của bộ lọc loại và loại địa điểm, hãy truy cập thêm về loại .

Thông số tùy chọn

Ba bộ lọc còn lại là không bắt buộc:

  • operating_status: Xác định trạng thái của những địa điểm cần bao gồm hoặc loại trừ. Mặc định là lọc theo operating_status: OPERATING_STATUS_OPERATIONAL (một giá trị cụ thể).
  • price_levels: Xác định mức giá của các địa điểm. Giá trị mặc định là không lọc (tất cả các mức giá đều có trong kết quả).
  • rating_filter: Xác định phạm vi điểm xếp hạng của các địa điểm. Giá trị mặc định là không lọc (tất cả điểm xếp hạng đều có trong kết quả).

Trạng thái hoạt động

Lọc dựa trên Trạng thái hoạt động (chẳng hạn như đang hoạt động hoặc tạm thời) đóng).

Mức giá

Lọc dựa trên Mức giá (chẳng hạn như miễn phí, trung bình hoặc đắt).

Bộ lọc xếp hạng

Lọc địa điểm dựa trên điểm xếp hạng trung bình của người dùng. Cả hai trường này đều là không bắt buộc và vì vậy nếu chúng bị bỏ qua, thì theo mặc định, chúng sẽ bao gồm cả địa điểm không có xếp hạng.

  • min_rating: Điểm xếp hạng trung bình tối thiểu từ người dùng (từ 1 đến 5).
  • max_rating: Điểm xếp hạng trung bình tối đa của người dùng (từ 1 đến 5).