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.
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. 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à chính xác dựa trên vùng 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ã 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 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 hơi cao so với diện tích thực tế (tối đa 2-3%) của 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 yêu cầu Geocoding API (API Địa chỉ). Phản hồi bao gồm mảng type liệt kê các loại địa điểm liên kết với mã địa điểm, chẳng hạn như city, neighborhood hoặc country.
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.street_number: cho biết số nhà chính xác.floor: cho biết tầng của địa chỉ toà nhà.post_box: cho biết một hộp thư bưu chính cụ thể.street_address: cho biết địa chỉ đường phố chính xác.room: cho biết phòng của địa chỉ toà nhà.intersection: cho biết một giao lộ chính, thường là của hai đường chính.landmark: cho biết một địa điểm lân cận được dùng làm thông tin tham khảo để hỗ trợ điều hướng.subpremise: cho biết một thực thể có thể định địa chỉ ở cấp dưới cơ sở, chẳng hạn như căn hộ, căn hộ hoặc căn hộ.sublocality_level_5: cấp độ chi tiết nhất của các thành phần địa chỉ tiểu khu vực. thường đại diện cho một tiểu khu vực rất nhỏ trong khu vực lân cận hoặc khu vực siêu địa phương trong một thành phố.
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. Một đ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.
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à toạ độ cuối cùng giống 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 đối xứng).
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 các mức giá của những địa điểm cần đưa vào. Theo mặc định, hệ thống sẽ không áp dụng bộ lọc cấp giá và trả về tất cả địa điểm (bao gồm cả những địa điểm không có thông tin về cấp giá).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
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ì kết quả sẽ chỉ bao gồm những địa điểm có trạng thái hoạt động là
OPERATING_STATUS_OPERATIONAL. - 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_CLOSEDhoặcOPERATING_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ị cấp 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 bạn không cung cấp bộ lọc: Tất cả địa điểm sẽ được trả về, bất kể các địa điểm đó có được chỉ định cấp giá hay không. Dữ liệu này bao gồm cả những địa điểm không có thông tin về mức giá. Những địa điểm này có thể không được trả về khi lọc theo mức giá cụ thể.
- Nếu bạn cung cấp một hoặc nhiều bộ lọc: Hệ thống sẽ chỉ trả về những địa điểm khớp với(các) mức giá đã chỉ định.
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).
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ớn hơn maxRating, thì lỗi INVALID_ARGUMENT sẽ được trả về.