Tài liệu này mô tả các tham số yêu cầu cho API Thông tin chi tiết về địa điểm, đồ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.
API Thông tin chi tiết về địa điểm 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 khớ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 những đị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 cách sử dụng API Địa điểm.
- 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ó sẵn bao gồm:
- Khu vực địa lý (vòng 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 API Thông tin chi tiết về địa điểm. 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í bộ lọc.Lưu ý: Nếu bạn chọn
INSIGHT_PLACES, API Thông tin chi tiết về địa điểm sẽ chỉ trả về mã địa điểm nếucountlà 100 trở xuống.
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 các loại sau:
circle: Xác định một khu vực dưới dạng 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ý dưới dạng hình tròn, bạn cần cung cấp center và radius. Tâm có thể là vĩ độ và kinh độ hoặc mã nhận dạng vị trí của tâm hình tròn.
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ã nhận dạng vị trí của tâm hình tròn. Xin lưu ý rằng chỉ hỗ trợ các địa điểm là điểm. 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. 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 khu vực bằng cách truyền mã địa điểm đến 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ể được biểu thị bằng đa giác). Ví dụ: mã địa điểm của Tampa, Florida 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, API Thông tin chi tiết về địa điểm sẽ trả về mã lỗi 404.
Bảng sau đây liệt kê các loại khu vực không được hỗ trợ. Để xác định xem mã địa điểm có đại diện cho một loại khu vực 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 khu vực liên kết với mã địa điểm, chẳng hạn như city, neighborhood hoặc country.
| 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 |
Khu vực 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. Đa giác phải có ít nhất 4 toạ độ, trong đó toạ độ đầu tiên và toạ độ cuối cùng giống nhau. Ít nhất 3 trong số các toạ độ được cung cấp phải là duy nhất. Ngoài toạ độ đầu tiên và cuối cùng, không được có toạ độ trùng lặp nào khác. 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 đố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à API Thông tin chi tiết về địa điểm hỗ trợ, hãy xem Bảng A trong phần Loại địa điểm cho API Địa điểm (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 bài viết tìm hiểu thêm 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 các bộ lọc sau:
operatingStatus: Chỉ định trạng thái của các địa điểm cần đưa vào hoặc loại trừ. Mặc định là lọc theooperatingStatus: OPERATING_STATUS_OPERATIONAL(một giá trị cụ thể).priceLevels: Chỉ định mức giá của các địa điểm. Theo mặc định là không lọc (tất cả các mức giá đều có trong kết quả).ratingFilter: Chỉ định phạm vi điểm xếp hạng của các địa điểm. Theo 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 cửa).
Mức giá
Lọc dựa trên Mức giá (chẳng hạn như miễn phí, vừa phải 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 không bắt buộc, vì vậy, nếu bạn bỏ qua các trường này, 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).