Tham số yêu cầu

Tài liệu này mô tả các tham số yêu cầu cho Places Aggregate API (API Tổng hợp địa điểm) và bao gồm thông tin chi tiết cũng như các phương pháp hay nhất để sử dụng dịch vụ này.

Places Aggregate 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 các tiêu chí cụ thể, chẳng hạn như loại địa điểm, 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 các địa điểm đáp ứng các bộ lọc đã chỉ định, sau đó tìm nạp thông tin chi tiết hơn bằng Places API.
Lọc linh hoạt: Áp dụng các bộ lọc toàn diện để nhận được thông tin tổng hợp chính xác Các bộ lọc có sẵn bao gồm:
- Khu vực địa lý (hình tròn, vùng hoặc đa giác tuỳ chỉnh)
- Loại địa điểm
- Trạng thái hoạt động
- Mức giá
- Phạm vi xếp hạng

Thông số bắt buộc

Phần này trình bày các tham số bắt buộc khi đưa ra yêu cầu cho Places Aggregate API. Mỗi yêu cầu phải cung cấp những thông tin sau:

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

Loại 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. Chúng tôi hỗ trợ các loại thông tin chi tiết sau:

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

Bộ 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 những loại sau:

circle: Xác định một khu vực 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 vùng.
customArea: Xác định một khu vực là một đa giác tuỳ chỉnh.

Hình tròn

Nếu chọn khu vực địa lý là một hình tròn, bạn cần cung cấp center và radius. center có thể là vĩ độ và kinh độ hoặc Mã địa điểm của tâm hình tròn. Phương thức này cho phép lọc chính xác và rõ ràng dựa trên khu vực hình tròn mà bạn xác định.

center:
- latLng: Vĩ độ và kinh độ của tâm hình tròn. Vĩ độ phải là một số nằm trong khoảng từ -90 đến 90. Kinh độ phải là một số nằm trong khoảng từ -180 đến 180.
- place: Mã địa điểm của tâm hình tròn. Xin lưu ý rằng chúng tôi chỉ hỗ trợ các địa điểm dạng điểm. Chuỗi này phải bắt đầu bằng tiền tố places/.
radius: Bán kính của hình tròn tính bằng mét. Số này phải là số dương.

Vùng

Xác định khu vực của bạn là một vùng bằng cách truyền mã địa điểm vào tham số place. Mã địa điểm đại diện cho một khu vực địa lý (chẳng hạn như một khu vực có thể biểu diễn bằng một đa giác). Ví dụ: mã địa điểm của Tampa, FL là places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Xin lưu ý rằng không phải tất cả mã địa điểm đều có hình học được xác định rõ ràng và trong những trường hợp này, Places Aggregate API sẽ trả về mã lỗi 400 kèm theo thông báo cho biết khu vực không được hỗ trợ. Ngoài ra, đối với các khu vực địa lý phức tạp, việc tối ưu hoá quy trình xử lý nội bộ có thể dẫn đến việc ước tính quá mức một chút về khu vực (tối đa 2 – 3%) đại diện cho khu vực đó.

Quan trọng: Khi sử dụng bộ lọc region với loại thông tin chi tiết INSIGHT_PLACES, các yêu cầu bao gồm các khu vực tranh chấp sẽ tự động bị từ chối để đảm bảo tính chính xác và tính trung lập của các dịch vụ của Google. Các khu vực tranh chấp là những khu vực có ranh giới xung đột hoặc tuyên bố chủ quyền lãnh thổ của các quốc gia hoặc thực thể khác nhau. Ranh giới tranh chấp được hiển thị dưới dạng đường gạch ngang màu xám trên Google Maps.

Để biết thêm thông tin về cách xác định các khu vực tranh chấp, hãy xem bài viết Tìm hiểu biên giới và tên quốc gia.

Để xác định xem một mã địa điểm có đại diện cho một loại địa điểm không được hỗ trợ hay không, hãy truyền mã địa điểm đó trong yêu cầu Geocoding API. Phản hồi bao gồm mảng type liệt kê các loại địa điểm được liên kết với Mã địa điểm, chẳng hạn như locality, neighborhood hoặc country. Một địa điểm sẽ bị từ chối lọc theo khu vực nếu bất kỳ loại nào của địa điểm đó khớp với danh sách này.

Các loại địa điểm không được hỗ trợ bao gồm:

establishment: thường cho biết một địa điểm chưa được phân loại.
intersection: cho biết một giao lộ lớn, thường là của hai con đường lớn.
subpremise: cho biết một thực thể có thể định địa chỉ bên dưới cấp độ cơ sở, chẳng hạn như căn hộ, đơn vị hoặc dãy phòng.

Khu vực tuỳ chỉnh

Xác định khu vực của một đa giác tuỳ chỉnh bằng cách sử dụng toạ độ vĩ độ và kinh độ.

Bạn có thể truy cập vào https://geojson.io/ để vẽ một đa giác tuỳ chỉnh và nhập các toạ độ đó vào yêu cầu. Một đa giác phải có tối thiểu 4 toạ độ, trong đó toạ độ đầu tiên và toạ độ cuối cùng giống hệt nhau. Ít nhất 3 trong số các toạ độ được cung cấp phải là duy nhất.

Các toạ độ giống hệt nhau liên tiếp sẽ được coi là một toạ độ. Tuy nhiên, các toạ độ trùng lặp không liên tiếp (ngoài toạ độ đầu tiên và toạ độ cuối cùng giống hệt nhau bắt buộc) sẽ dẫn đến lỗi.

Ngoài ra, các cạnh không liền kề không được phép giao nhau và các cạnh có độ dài 180 độ không được phép (tức là các đỉnh liền kề không thể đối diện nhau).

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 cần đưa vào hoặc loại trừ. Để biết danh sách cả loại địa điểm chính và phụ mà Places Aggregate API hỗ trợ, hãy xem Bảng A trong phần Loại địa điểm cho Places API (Mới). Bạn phải chỉ định ít nhất một loại includedTypes hoặc includedPrimaryTypes.

includedTypes: Danh sách các loại địa điểm được đưa vào.
excludedTypes: Danh sách các loại địa điểm bị loại trừ.
includedPrimaryTypes: Danh sách các loại địa điểm chính được đưa vào.
excludedPrimaryTypes: 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 xem thêm thông tin về bộ lọc loại.

Lưu ý: Bộ lọc loại tự động bao gồm các loại phụ của các loại đã chỉ định. Ví dụ: nếu bạn lọc theo gym, kết quả cũng bao gồm các địa điểm được phân loại theo các loại phụ của địa điểm đó, chẳng hạn như yoga_studio.

Thông số tùy chọn

Đây là các bộ lọc không bắt buộc:

operatingStatus: Chỉ định trạng thái của các địa điểm cần đưa vào hoặc loại trừ. Theo mặc định, bộ lọc sẽ lọc theo operatingStatus: OPERATING_STATUS_OPERATIONAL (một giá trị cụ thể).
priceLevels: Chỉ định mức giá của các địa điểm cần đưa vào. Theo mặc định, không có bộ lọc mức giá nào được áp dụng và tất cả các địa điểm (kể cả những địa điểm không có thông tin về mức giá) đều được trả về.
ratingFilter: Chỉ định phạm vi xếp hạng của các địa điểm. Theo mặc định, không có bộ lọc nào được áp dụng (tất cả điểm xếp hạng đều được đưa vào kết quả).

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

Với bộ lọc operatingStatus, bạn có thể lọc dựa trên Trạng thái hoạt động chẳng hạn như OPERATIONAL hoặc TEMPORARILY_CLOSED. Hành vi của bộ lọc operatingStatus hoạt động như sau:

Nếu không có bộ lọc nào được cung cấp, thì chỉ những địa điểm có trạng thái hoạt động là OPERATING_STATUS_OPERATIONAL mới được đưa vào kết quả.
Nếu bạn cung cấp một hoặc nhiều bộ lọc, bạn phải chỉ định các giá trị trạng thái hoạt động hợp lệ (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED hoặc OPERATING_STATUS_TEMPORARILY_CLOSED).

Mức giá

Với bộ lọc priceLevels, bạn có thể lọc địa điểm dựa trên Mức giá của địa điểm đó. Các giá trị mức giá hợp lệ là: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE và PRICE_LEVEL_VERY_EXPENSIVE.

Hành vi của bộ lọc priceLevels như sau:

Nếu không có bộ lọc nào được cung cấp: Tất cả các địa điểm đều được trả về, bất kể địa điểm đó có được chỉ định mức giá hay không. Điều này bao gồm cả những địa điểm không có thông tin về mức giá, có thể không được trả về khi lọc theo các mức giá cụ thể.
Nếu bạn cung cấp một hoặc nhiều bộ lọc: Chỉ những địa điểm khớp với(các) mức giá đã chỉ định mới được trả về.

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 không bắt buộc, vì vậy, nếu bạn bỏ qua, chúng sẽ mặc định bao gồm cả những địa điểm không có điểm xếp hạng.

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

Ngoài ra, giá trị minRating phải luôn nhỏ hơn hoặc bằng giá trị maxRating. Nếu minRating được chỉ định là lớn hơn maxRating, thì lỗi INVALID_ARGUMENT sẽ được trả về.