Tìm kiếm lân cận (Mới) yêu cầu nhận một hoặc nhiều loại địa điểm và trả về một danh sách các địa điểm phù hợp trong vùng cụ thể. Mặt nạ trường chỉ định một hoặc nhiều loại dữ liệu là trường bắt buộc. 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 để bạn có thể làm quen với API và Tuỳ chọn API:
Hãy làm thử!Hãy thử thuộc tính tương tác bản minh hoạ để xem kết quả Tìm kiếm lân cận (Mới) được hiển thị 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à một yêu cầu POST qua HTTP tới một URL 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
Place
. Đối tượngPlace
chứa thông tin chi tiết về một địa điểm. - FieldMask được chuyển trong yêu cầu chỉ định danh sách các trường
đã 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 này bằng cách sử dụng tham số URL
$fields
hoặcfields
hoặc bằng cách sử dụng 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 sẽ không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý không cần thiết và các khoản phí thanh toán.
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
,places.types
,places.utcOffsetMinutes
,places.viewport
* Trườngplaces.name
chứa địa điểm tên tài nguyên trong biểu mẫu:places/PLACE_ID
. 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.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 nó trong yêu cầu của bạn 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 duy nhất trong các loại Bảng A được liên kết với nó. Ví dụ: loại chính có thể là
"mexican_restaurant"
hoặc"steak_house"
. Sử dụngincludedPrimaryTypes
vàexcludedPrimaryTypes
để lọc kết quả loại hình 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 liên kết với cuộc trò chuyện đó. Ví dụ: một nhà hàng có thể có các loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
"establishment"
,"point_of_interest"
. Sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả trên danh sách các loại được liên kết với một địa điểm.Khi bạn chỉ định một loại chính chung, chẳng hạn như
"restaurant"
hoặc"hotel"
, câu trả lời có thể chứa các địa điểm có loại chính cụ thể hơn đồng hồ hẹn giờ được chỉ định. Ví dụ: bạn chỉ định bao gồm loại chính"restaurant"
. Sau đó, câu trả lời có thể chứa địa điểm có loại chính là"restaurant"
, nhưng câu trả lời cũng có thể chứa những địa điểm có từ khoá cụ thể hơn loại chính, chẳng hạn như"chinese_restaurant"
hoặc"seafood_restaurant"
.Nếu nội dung tìm kiếm được chỉ định với hạn chế nhiều loại, thì chỉ địa điểm đáp ứng tất cả các hạn chế sẽ được trả về. Ví dụ: nếu bạn chỉ định
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, địa điểm được trả lại cung cấp"restaurant"
dịch vụ liên quan 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 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ì hàm này câu trả lời bao gồm các địa điểm được phân loại là"school"
nhưng không phải là"primary_school"
. Câu trả lời bao gồm các địa điểm khớp với ít nhất một củaincludedTypes
và không có mục 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ì hệ thống sẽ trả về lỗiINVALID_REQUEST
.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 cần bao gồm trong một 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 cần loại trừ khỏi một lượt tìm kiếm.
Nếu có bất kỳ loại chính nào xung đột với nhau, chẳng hạn như một loại xuất hiện trong cả hai
includedPrimaryTypes
vàexcludedPrimaryTypes
, một thuộc tính Trả về lỗiINVALID_ARGUMENT
. -
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ể không đầ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ềINVALID_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ùng có thể đọc được tại địa phương. Để đạt được mục tiêu đó, công cụ này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc nếu cần, tuân theo ngôn ngữ. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Các thành phần địa chỉ là tất cả đượ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 nhóm kết quả mà API chọn trả lại hàng và thứ tự mà chúng được trả về. Bộ mã hoá địa lý giải thích các chữ viết tắt khác nhau tuỳ theo 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ệ bằng một ngôn ngữ nhưng không hợp lệ bằng ngôn ngữ khác.
-
maxResultCount
Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Giá trị phải nằm trong khoảng 1 và 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í được chỉ định.
-
regionCode
Mã vùng dùng để định dạng phản hồi, được chỉ định làm mã CLDR gồm 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
, mã quốc gia bị bỏ khỏiformattedAddress
. Thông số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm quốc gia) tên hoặc trênshortFormattedAddress
, mà không bao giờ có tên đó.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à "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "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 yêu cầu Tìm kiếm lân cận (Mới) đối với màn hình
tên 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
.
Phản hồi
thì 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
để bao gồm
địa chỉ nhà hàng, loại và địa chỉ web trong 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 ở 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 thể hiện yêu cầu Tìm kiếm lân cận (Mới) đối với lệnh
hiển thị tên tất cả các cửa hàng tiện lợi và cửa hàng rượu trong vòng bán kính 1000 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 sẽ thêm
places.primaryType
và places.types
vào mặt nạ trường
để câu trả lời bao gồm thông tin về loại về mỗi địa điểm, giúp bạn dễ dàng chọn
vị trí thích hợp khỏi kết quả.
Loại trừ loại địa điểm khỏi kết quả tìm kiếm
Ví dụ sau đây thể hiện yêu cầu về tính năng Tìm kiếm lân cận (Mới) cho tất cả địa điểm
loại "school"
, không bao gồm tất 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 về tính năng Tìm kiếm lân cận (Mới) cho các địa điểm
gần một địa điểm trong trung tâm thành phố San Francisco. Trong ví dụ này, bạn đưa rankPreference
vào
tham số để xếp hạng 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 thực hiện các yêu cầu mẫu để mà bạn 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 Hiển thị các tham số chuẩn rồi đặt
tham số
fields
vào 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.