Yêu cầu Tìm kiếm lân cận (Mới) sẽ nhận một hoặc nhiều loại địa điểm và trả về danh sách các địa điểm phù hợp trong khu vực đã chỉ định. Cần có mặt nạ trường để chỉ định một hoặc nhiều loại dữ liệu. Tính năng Tìm kiếm lân cận (Mới) chỉ hỗ trợ các yêu cầu POST.
API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để làm quen với API và các tuỳ chọn API:
Hãy làm thử!Hãy thử bản minh hoạ tương tác để xem kết quả Tìm kiếm lân cận (Mới) xuất hiện trên bản đồ.
Yêu cầu Tìm kiếm lân cận (Mới)
Yêu cầu Tìm kiếm lân cận (Mới) là yêu cầu POST qua HTTP tới một URL có trong biểu mẫu:
https://places.googleapis.com/v1/places:searchNearby
Truyền tất cả các tham số trong nội dung của yêu cầu JSON hoặc trong tiêu đề dưới dạng một phần của yêu cầu POST. Ví dụ:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Câu trả lời cho tính năng Tìm kiếm lân cận (Mới)
Tính năng Tìm kiếm lân cận (Mới) trả về một đối tượng JSON làm phản hồi. Trong câu trả lời:
- Mảng
places
chứa tất cả các địa điểm phù hợp. - Mỗi vị trí trong mảng được biểu thị bằng một đối tượng
Place
. Đối tượngPlace
chứa thông tin chi tiết về một địa điểm. - FieldMask (Mặt nạ trường) được chuyển trong yêu cầu sẽ chỉ định danh sách các trường được trả về trong đối tượng
Place
.
Đối tượng JSON hoàn chỉnh có dạng:
{ "places": [ { object (Place) } ] }
Thông số bắt buộc
-
FieldMask
Chỉ định danh sách các trường sẽ trả về trong phản hồi bằng cách tạo một mặt nạ trường phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tham số URL
$fields
hoặcfields
hay tiêu đề HTTPX-Goog-FieldMask
. Không có danh sách mặc định gồm các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường, phương thức này sẽ trả về lỗi.Tạo mặt nạ cho trường là một phương pháp thiết kế hiệu quả để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và các khoản phí thanh toán không cần thiết.
Chỉ định danh sách các loại dữ liệu địa điểm được phân tách bằng dấu phẩy cần trả về. Ví dụ: để truy xuất tên hiển thị và địa chỉ của địa điểm.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Sử dụng
*
để truy xuất tất cả các trường.X-Goog-FieldMask: *
Chỉ định một hoặc nhiều trường sau:
Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Cơ bản):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
, ,places.subDestinations
, , , , , , , , , {2,places.shortFormattedAddress
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Hãy sử dụngplaces.displayName
để truy cập vào tên dạng văn bản của địa điểm.Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Nâng cao):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Ưu tiên):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.delivery
,places.servesBreakfast
,places.servesBreakfast
,places.delivery
,places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Vùng để tìm kiếm được chỉ định dưới dạng một hình tròn, được xác định bởi điểm tâm và bán kính tính b���ng mét. Bán kính phải nằm trong khoảng từ 0,0 đến 50000,0, bao gồm cả hai giá trị đó. Bán kính mặc định là 0.0. Bạn phải đặt tham số này trong yêu cầu của mình thành một giá trị lớn hơn 0,0.
Ví dụ:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Thông số tùy chọn
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Cho phép bạn chỉ định danh sách các loại trong các loại Bảng A dùng để lọc kết quả tìm kiếm. Bạn có thể chỉ định tối đa 50 loại trong mỗi danh mục hạn chế loại.
Một địa điểm chỉ có thể có một loại chính trong các loại Bảng A liên kết với địa điểm đó. Ví dụ: loại chính có thể là
"mexican_restaurant"
hoặc"steak_house"
. Hãy sử dụngincludedPrimaryTypes
vàexcludedPrimaryTypes
để lọc kết quả theo loại chính của một địa điểm.Một địa điểm cũng có thể có nhiều giá trị loại từ các loại Bảng A được liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có những loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Hãy sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả theo danh sách các loại liên kết với một địa điểm.Nếu một lượt tìm kiếm được chỉ định với nhiều hạn chế về loại, thì chỉ những vị trí đáp ứng tất cả các hạn chế đó mới được trả về. Ví dụ: nếu bạn chỉ định
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, thì các vị trí được trả về cung cấp các dịch vụ liên quan đến"restaurant"
nhưng không hoạt động chủ yếu dưới dạng"steak_house"
.includedTypes
Danh sách các loại địa điểm được phân tách bằng dấu phẩy trong Bảng A cần tìm. Nếu tham số này bị bỏ qua, hàm sẽ trả về tất cả các loại địa điểm.
excludedTypes
Danh sách các loại địa điểm được phân tách bằng dấu phẩy trong Bảng A để loại trừ khỏi kết quả tìm kiếm.
Nếu bạn chỉ định cả
includedTypes
( chẳng hạn như"school"
) vàexcludedTypes
(chẳng hạn như"primary_school"
) trong yêu cầu, thì phản hồi sẽ bao gồm các vị trí được phân loại là"school"
chứ không phải là"primary_school"
. Phản hồi bao gồm các vị trí khớp với ít nhất một trong sốincludedTypes
và không có vị trí nào trong sốexcludedTypes
.Nếu có bất kỳ loại xung đột nào, chẳng hạn như một loại xuất hiện trong cả
includedTypes
vàexcludedTypes
, thì lỗiINVALID_REQUEST
sẽ được trả về.includedPrimaryTypes
Danh sách các loại địa điểm chính được phân tách bằng dấu phẩy trong Bảng A để đưa vào nội dung tìm kiếm.
excludedPrimaryTypes
Danh sách các loại địa điểm chính được phân tách bằng dấu phẩy trong Bảng A để loại trừ khỏi kết quả tìm kiếm.
Nếu có bất kỳ kiểu chính nào xung đột, chẳng hạn như một kiểu xuất hiện trong cả
includedPrimaryTypes
vàexcludedPrimaryTypes
, thì lỗiINVALID_ARGUMENT
sẽ được trả về. -
languageCode
Ngôn ngữ mà kết quả trả về.
- Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
- Nếu bạn không cung cấp
languageCode
, thì API mặc định sẽ làen
. Nếu bạn chỉ định mã ngôn ngữ không hợp lệ, API sẽ trả về lỗiINVALID_ARGUMENT
. - API này sẽ cố gắng hết sức để cung cấp địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, công cụ này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang tập lệnh mà người dùng có thể đọc nếu cần, qua đó quan sát ngôn ngữ ưu tiên. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
- Nếu tên không có sẵn bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả phù hợp nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về các kết quả đó. Bộ mã hoá địa lý diễn giải các chữ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho loại đường phố, hoặc từ đồng nghĩa có thể hợp lệ ở ngôn ngữ này nhưng không hợp lệ ở ngôn ngữ khác.
-
maxResultCount
Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Phải nằm trong khoảng từ 1 đến 20 (mặc định).
-
rankPreference
Loại thứ hạng sẽ sử dụng. Nếu tham số này bị bỏ qua, các kết quả được xếp hạng theo mức độ phổ biến. Có thể là một trong những trạng thái sau:
POPULARITY
(mặc định) Sắp xếp kết quả dựa trên mức độ phổ biến.DISTANCE
Sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí đã chỉ định.
-
regionCode
Mã vùng dùng để định dạng phản hồi, được ch�� định dưới dạng giá trị mã CLDR hai ký tự. Không có giá trị mặc định.
Nếu tên quốc gia của trường
formattedAddress
trong phản hồi khớp vớiregionCode
, thì mã quốc gia sẽ bị bỏ qua trongformattedAddress
. Thông số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm tên quốc gia) hoặc trênshortFormattedAddress
(không bao giờ có tên quốc gia).Hầu hết mã CLDR đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của mã này là "gb" (về mặt kỹ thuật là "Vương quốc Anh" và Bắc Ireland). Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.
Ví dụ về tính năng Tìm kiếm lân cận (Mới)
Tìm địa điểm thuộc một loại
Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm lân cận (Mới) đối với tên hiển thị của tất cả các nhà hàng trong bán kính 500 mét, do circle
xác định:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Xin lưu ý rằng tiêu đề X-Goog-FieldMask
chỉ định rằng phản hồi chứa các trường dữ liệu sau: places.displayName
.
Sau đó, phản hồi sẽ có dạng:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Thêm các loại dữ liệu khác vào mặt nạ trường để trả về thông tin bổ sung.
Ví dụ: thêm places.formattedAddress,places.types,places.websiteUri
để đưa địa chỉ, loại và địa chỉ web của nhà hàng vào câu trả lời:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
Phản hồi hiện có dạng:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Tìm địa điểm thuộc nhiều loại
Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm lân cận (Mới) cho tên hiển thị của tất cả các cửa hàng tiện lợi và cửa hàng rượu trong phạm vi bán kính 1.000 mét của circle
được chỉ định:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyVí dụ này thêm
places.primaryType
và places.types
vào mặt nạ trường để phản hồi bao gồm thông tin về loại về từng địa điểm, giúp bạn dễ dàng chọn địa điểm phù hợp trong kết quả.
Loại trừ loại địa điểm khỏi kết quả tìm kiếm
Ví dụ sau đây cho thấy một yêu cầu về tính năng Tìm kiếm lân cận (Mới) cho tất cả các địa điểm thuộc loại "school"
, ngoại trừ tất cả các địa điểm thuộc loại "primary_school"
, xếp hạng kết quả theo khoảng cách:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Tìm kiếm tất cả địa điểm gần một khu vực, xếp hạng theo khoảng cách
Ví dụ sau đây cho thấy yêu cầu Tìm kiếm lân cận (Mới) cho các địa điểm gần một điểm trong trung tâm thành phố San Francisco. Trong ví dụ này, bạn đưa tham số rankPreference
vào để xếp hạng các kết quả theo khoảng cách:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Hãy dùng thử!
API Explorer cho phép bạn đưa ra các yêu cầu mẫu để có thể làm quen với API và các tuỳ chọn API.
- Chọn biểu tượng API ở bên phải của trang.
- (Không bắt buộc) Mở rộng tuỳ chọn Show standard parameters (Hiện các tham số chuẩn) và đặt tham số
fields
thành fieldMask (mặt nạ trường). - Chỉnh sửa Nội dung yêu cầu (không bắt buộc).
- Chọn nút Thực thi. Trong cửa sổ bật lên, hãy chọn tài khoản mà bạn muốn dùng để gửi yêu cầu.
Trong bảng điều khiển API Explorer, hãy chọn biểu tượng mở rộng để mở rộng cửa sổ API Explorer.