Tham số yêu cầu

Tài liệu này mô tả các thông số yêu cầu cho Places Aggregate API, đồng thời cung cấp thông tin chi tiết và 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 số lượng địa điểm: Xác định số lượng địa điểm đáp ứng các tiêu chí cụ thể, 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 những địa điểm đáp ứng các bộ lọc đượ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 bộ lọc toàn diện để nhận được số liệu 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, khu vực 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 phân loại

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.
  • 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. Các loại thông tin chi tiết sau đây được hỗ trợ:

  • 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 khớp với tiêu chí lọc.

Bộ lọc

Chỉ định tiêu chí lọc địa điểm. Tối thiểu, 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 vòng 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 dưới dạng đ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à hiệu quả 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ỉ những địa điểm dạng điểm mới đượ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 hình tròn tính bằng mét. Số này phải là số dương.
Khu vực

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 thị 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 mã địa điểm nào cũng 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 này 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 hơi quá mức diện tích (tối đa 2-3%) đại diện cho khu vực.

Để xác định xem 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 một 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 mã đị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ợ:

  • 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 đường chính.
  • 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.
Vùng tuỳ chỉnh

Xác định diện tích 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à toạ độ riêng biệt.

Các toạ độ giống hệt nhau liên tiếp sẽ được coi là một toạ độ duy nhất. Tuy nhiên, các toạ độ trùng lặp không liên tiếp (ngoài toạ độ đầu tiên và 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 được phép đối cự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 cần đưa vào hoặc loại trừ. Để xem 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ông tin khác về bộ lọc loại.

Thông số tùy chọn

Bạn không bắt buộc phải sử dụng những bộ lọc này:

  • operatingStatus: Chỉ định trạng thái của những địa điểm cần đưa vào hoặc loại trừ. Mặc định là lọc theo operatingStatus: OPERATING_STATUS_OPERATIONAL (một giá trị cụ thể).
  • priceLevels: Chỉ định các mức giá của những đị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ả đị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 điểm xếp hạng của các địa điểm. Theo mặc định, không có bộ lọc (tất cả các mức phân loại đề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 bạn không cung cấp bộ lọc nào, 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 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ác giá trị hợp lệ cho cấp độ giá 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 bạn không cung cấp bộ lọc nào: Tất 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 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á được chỉ định mới được trả về.

Bộ lọc xếp hạng

Lọc cá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 các trường này, thì theo mặc định, các trường này cũng sẽ bao gồm 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 của người dùng (từ 1 đến 5).
  • maxRating: Điểm xếp hạng trung bình tối đa của người dùng (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ề.