Yêu cầu Tìm kiếm lân cận (Mới) yêu cầu 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. Bạn cần phải có mặt nạ trường (field mask) chỉ định một hoặc nhiều loại dữ liệu. 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à các tuỳ chọn API:
Hãy làm thử!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 cho một URL ở dạng:
https://places.googleapis.com/v1/places:searchNearby
Truyền tất cả tham số trong nội dung yêu cầu JSON hoặc trong tiêu đề như 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
Phản hồi về tính năng Tìm kiếm lân cận (Mới)
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 duy nhất. - FieldMask (Mặt nạ) được truyền vào 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 trường cần trả về trong phản hồi bằng cách tạo 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
hayfields
, hoặc bằng tiêu đề HTTPX-Goog-FieldMask
. Không có danh sách mặc định các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường (field mask), phương thức sẽ trả về một lỗi.Che giấu trường là một phương pháp thiết kế hay để đảm bảo 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à 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ần trả về, được phân tách bằng dấu phẩy. 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ính năng Tìm kiếm lân cận (Cơ bản):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,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.subDestinations
, , ,places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Sử dụngplaces.displayName
để truy cập vào tên văn bản của địa điểm.Các trường sau đây kích hoạt SKU của tính năng 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 sẽ 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.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.servesBeer
,places.delivery
,places.menuForChildren
,places.menuForChildren
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Khu vực cần tìm kiếm được chỉ định dưới dạng một vòng 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. 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.
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 thuộ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ế về loại.
Một địa điểm chỉ có thể có một loại chính trong số các loại Bảng A được 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ả về loại địa điểm chính.Một địa điểm cũng có thể có nhiều giá trị loại trong số các loại Bảng A liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có các loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả trong danh sách các loại liên kết với một địa điểm.Nếu một cụm từ tìm kiếm được chỉ định kèm theo nhiều lựa chọn hạn chế về loại, thì hệ thống chỉ trả về những địa điểm đáp ứng tất cả hạn chế này. Ví dụ: nếu bạn chỉ định
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, thì các địa điểm được trả về sẽ 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 từ Bảng A cần tìm kiếm. Nếu tham số này bị bỏ qua, hàm sẽ trả về các địa điểm thuộc tất cả các loại.
excludedTypes
Danh sách các loại địa điểm được phân tách bằng dấu phẩy từ 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ì 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 trongincludedTypes
và không có nơi nào trongexcludedTypes
.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 từ 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 từ Bảng A để loại trừ khỏi kết quả 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ả
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 các ngôn ngữ được hỗ trợ. Google thường cập nhật các ngôn ngữ được hỗ trợ, nên danh sách này có thể chưa đầy đủ.
- Nếu bạn không cung cấp
languageCode
, 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 sẽ cố gắng hết sức để cung cấp một đị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 đó, phương thức này 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, đồng thời 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, thì API sẽ sử dụng kết quả khớ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ề, cũng như thứ tự trả về các kết quả đó. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như cách viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ trong 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 từ 1 đến 20 (mặc định).
-
rankPreference
Loại xếp hạng sẽ sử dụng. Nếu thông số này bị bỏ qua, thì các kết quả sẽ đượ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 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
, thì mã quốc gia sẽ bị loại khỏiformattedAddress
. Tham số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm tên quốc gia) hoặc đối vớishortFormattedAddress
(không bao giờ bao gồm tên quốc gia).Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, trừ một số trường hợp 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 là "gb" (về mặt kỹ thuật, là pháp nhân của "Vương quốc Anh và Bắc Ireland"). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
Ví dụ về Tìm kiếm lân cận (Mới)
Tìm một loại địa điểm
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 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
.
Khi đó, 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 (field mask) để trả về thông tin bổ sung.
Ví dụ: thêm places.formattedAddress,places.types,places.websiteUri
để đưa địa chỉ nhà hàng, loại và địa chỉ web vào phản hồ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 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ạ cho trường (field mask) để phản hồi bao gồm thông tin loại về từng địa điểm, giúp bạn dễ dàng chọn địa điểm thích hợp trong kết quả.
Loại trừ một 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 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 một 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 vào tham số rankPreference
để 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 thực hiện các yêu cầu mẫu để bạn có thể làm quen với các 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 mục Show standard parameters (Hiện thông số chuẩn) và đặt tham số
fields
thành field mask (mặt nạ trường). - Chỉnh sửa Nội dung yêu cầu nếu muốn.
- 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.