Thao tác Tìm kiếm bằng văn bản (Mới) sẽ trả về thông tin về một nhóm địa điểm dựa trên một chuỗi, ví dụ: "pizza ở New York" hoặc "cửa hàng giày gần Ottawa" hoặc "123 Main Street". Dịch vụ này phản hồi bằng danh sách các địa điểm khớp với chuỗi văn bản và mọi độ lệch vị trí đã được đặt.
Dịch vụ này đặc biệt hữu ích khi thực hiện truy vấn địa chỉ không rõ ràng trong một hệ thống tự động, và các thành phần không phải địa chỉ của chuỗi có thể khớp với cả doanh nghiệp và địa chỉ. Ví dụ về truy vấn địa chỉ không rõ ràng là các địa chỉ hoặc yêu cầu có định dạng không chuẩn, bao gồm các thành phần không phải địa chỉ như tên doanh nghiệp. Các yêu cầu như 2 ví dụ đầu tiên trong bảng sau đây có thể trả về kết quả bằng 0 trừ phi bạn đặt một vị trí (chẳng hạn như khu vực, hạn chế về vị trí hoặc sai lệch về vị trí).
"10 High Street, UK" hoặc "123 Main Street, US" | Nhiều "High Street" ở Vương quốc Anh; nhiều "Main Street" ở Hoa Kỳ. Truy vấn không trả về kết quả mong muốn trừ khi bạn đặt giới hạn vị trí. |
"ChainRestaurant New York" | Nhiều địa điểm "ChainRestaurant" ở New York; không có địa chỉ đường phố hoặc thậm chí là tên đường. |
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US" | Chỉ có một "High Street" (Đường chính) ở thành phố Escher, Vương quốc Anh; chỉ có một "Main Street" (Đường chính) ở thành phố Pleasanton, California, Hoa Kỳ. |
"UniqueRestaurantName New York" | Chỉ có một cơ sở có tên này ở New York; không cần địa chỉ đường để phân biệt. |
"nhà hàng pizza ở New York" | Truy vấn này chứa quy định hạn chế về vị trí và "nhà hàng pizza" là một loại địa điểm được xác định rõ ràng. Hàm này trả về nhiều kết quả. |
"+1 514-670-8700" | Truy vấn này chứa số điện thoại. Hàm này trả về nhiều kết quả cho các địa điểm liên kết với số điện thoại đó. |
Trình khám phá API cho phép bạn tạo các yêu cầu trực tiếp để làm quen với API và các tuỳ chọn API:
Yêu cầu Tìm kiếm bằng văn bản
Yêu cầu Tìm kiếm văn bản là một yêu cầu POST HTTP có dạng như sau:
https://places.googleapis.com/v1/places:searchText
Truyền tất cả tham số trong phần 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 '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
Câu trả lời của tính năng Tìm kiếm văn bản (Mới)
Tìm kiếm văn bản (Mới) trả về một đối tượng JSON dưới dạng phản hồi. Trong phản hồi:
- Mảng
places
chứa tất cả địa điểm trùng khớ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 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
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 về 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.Việc che trường là một phương pháp thiết kế hay để đả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í 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 để 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 văn bản (chỉ mã nhận dạng):
places.attributions
,places.id
,places.name
*,nextPageToken
* Trườngplaces.name
chứa tên tài nguyên ở dạng:places/PLACE_ID
. Sử dụngplaces.displayName
để truy cập tên văn bản của địa điểm.Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (Cơ bản):
places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsLinks
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
Các trường sau đây kích hoạt SKU Tìm kiếm văn bản (Nâng cao):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.priceRange
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bả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.routingSummaries
,*places.servesBeer
,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDessert
,places.servesDinner
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
* Chỉ tìm kiếm bằng văn bản và tìm kiếm xung quanh
-
textQuery
Chuỗi văn bản để tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "địa điểm tham quan tốt nhất ở San Francisco". API này trả về các kết quả trùng khớp dựa trên chuỗi này và sắp xếp các kết quả dựa trên mức độ liên quan được nhận thấy.
Thông số tùy chọn
includedType
Hạn chế kết quả ở những địa điểm khớp với loại được chỉ định do Bảng A xác định. Bạn chỉ có thể chỉ định một loại. Ví dụ:
"includedType":"bar"
"includedType":"pharmacy"
-
includePureServiceAreaBusinesses
Nếu bạn đặt thành
true
, phản hồi sẽ bao gồm những doanh nghiệp trực tiếp đến thăm hoặc giao hàng cho khách hàng, nhưng không có địa điểm kinh doanh thực tế. Nếu bạn đặt thànhfalse
, API này chỉ trả về những doanh nghiệp có địa điểm doanh nghiệp thực tế. languageCode
Ngôn ngữ dùng để trả về kết quả.
- 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ợ nên danh sách này có thể không đầy đủ.
-
Nếu bạn không cung cấp
languageCode
, API sẽ mặc định 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 cố gắng 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 đó, API 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 được nếu cần, tuân theo ngôn ngữ ưu tiên. Tất cả địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất 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 không có tên nào bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên khớp gần 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ả đó. Trình 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ư từ viết tắt cho các loại đường hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác.
locationBias
Chỉ định một vùng để tìm kiếm. Vị trí này đóng vai trò là độ lệch, nghĩa là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực đã chỉ định.
Bạn có thể chỉ định
locationRestriction
hoặclocationBias
, nhưng không được chỉ định cả hai. Bạn có thể coilocationRestriction
là khu vực chỉ định kết quả, cònlocationBias
là khu vực cho biết kết quả có thể ở bên trong hoặc gần nhưng cũng có thể ở bên ngoài khu vực đó.Chỉ định khu vực dưới dạng Khung nhìn hình chữ nhật hoặc vòng tròn.
Đường tròn được xác định bằng tâm điể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 đến 50000. Bán kính mặc định là 0.0. Ví dụ:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Hình chữ nhật là khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm thấp và cao đối diện nhau theo đường chéo. Điểm thấp đánh dấu góc Tây Nam của hình chữ nhật, còn điểm cao biểu thị góc Đông Bắc của hình chữ nhật.
Một khung nhìn được coi là một khu vực đóng, có nghĩa là khu vực đó bao gồm cả ranh giới của khung nhìn đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ:
- Nếu
low
=high
, khung nhìn sẽ bao gồm một điểm duy nhất đó. - Nếu
low.longitude
>high.longitude
, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn sẽ vượt qua đường kinh độ 180 độ). - Nếu
low.longitude
= -180 độ vàhigh.longitude
= 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ. - Nếu
low.longitude
= 180 độ vàhigh.longitude
= -180 độ, thì phạm vi kinh độ sẽ trống. - Nếu
low.latitude
>high.latitude
, thì phạm vi vĩ độ sẽ trống.
Bạn phải điền cả giá trị thấp và cao, đồng thời hộp được biểu thị không được để trống. Khung nhìn trống sẽ dẫn đến lỗi.
Ví dụ: khung nhìn này bao gồm toàn bộ Thành phố New York:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Nếu
locationRestriction
Chỉ định một khu vực để tìm kiếm. Kết quả nằm ngoài khu vực đã chỉ định sẽ không được trả về.
Chỉ định vùng dưới dạng Khung nhìn hình chữ nhật. Để xem ví dụ về cách xác định Khung nhìn, hãy xem nội dung mô tả về
locationBias
.Bạn có thể chỉ định
locationRestriction
hoặclocationBias
, nhưng không thể chỉ định cả hai. Hãy coilocationRestriction
là chỉ định vùng mà kết quả phải nằm trong đó vàlocationBias
là chỉ định vùng mà kết quả có thể nằm bên trong hoặc gần đó nhưng có thể nằm bên ngoài khu vực.-
maxResultCount (không dùng nữa)
Chỉ định số lượng kết quả (từ 1 đến 20) hiển thị trên mỗi trang. Ví dụ: việc đặt giá trị
maxResultCount
là 5 sẽ trả về tối đa 5 kết quả trên trang đầu tiên. Nếu có nhiều kết quả hơn có thể được trả về từ truy vấn, thì phản hồi sẽ bao gồm mộtnextPageToken
mà bạn có thể truyền vào một yêu cầu tiếp theo để truy cập vào trang tiếp theo. evOptions
Chỉ định các thông số để xác định giắc cắm sạc và tốc độ sạc có sẵn cho xe điện (EV).
connectorTypes
Lọc theo loại đầu sạc xe điện có tại một địa điểm. Một vị trí không hỗ trợ bất kỳ loại đầu nối nào sẽ bị lọc ra. Các loại đầu nối sạc xe điện được hỗ trợ bao gồm bộ sạc kết hợp (AC và DC), bộ sạc Tesla, bộ sạc tuân thủ GB/T (dùng để sạc nhanh xe điện ở Trung Quốc) và bộ sạc ổ cắm trên tường. Để biết thêm thông tin, hãy xem tài liệu tham khảo.
minimumChargingRateKw
Lọc các địa điểm theo mức sạc tối thiểu cho xe điện tính bằng kilowatt (kW). Mọi vị trí có mức giá sạc thấp hơn mức giá sạc tối thiểu sẽ bị lọc ra. Ví dụ: để tìm bộ sạc xe điện có tốc độ sạc ít nhất là 10 kW, bạn có thể đặt tham số này thành "10".
minRating
Chỉ giới hạn kết quả ở những người dùng có điểm xếp hạng trung bình từ người dùng lớn hơn hoặc bằng hạn mức này. Giá trị phải nằm trong khoảng từ 0 đến 5 (tính cả hai giá trị này) với mức tăng 0,5. Ví dụ: 0, 0,5, 1,0, ... , 5,0. Các giá trị được làm tròn lên đến 0,5 gần nhất. Ví dụ: giá trị 0,6 sẽ loại bỏ tất cả kết quả có điểm xếp hạng dưới 1,0.
openNow
Nếu là
true
, chỉ trả về những địa điểm đang mở cửa kinh doanh tại thời điểm gửi truy vấn. Nếu làfalse
, hãy trả về tất cả các doanh nghiệp bất kể trạng thái mở cửa. Những địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu Google Địa điểm sẽ được trả về nếu bạn đặt tham số này thànhfalse
.pageSize
Chỉ định số lượng kết quả (từ 1 đến 20) để hiển thị trên mỗi trang. Ví dụ: việc đặt giá trị
pageSize
là 5 sẽ trả về tối đa 5 kết quả trên trang đầu tiên. Nếu có nhiều kết quả hơn có thể được trả về từ truy vấn, thì phản hồi sẽ bao gồm mộtnextPageToken
mà bạn có thể truyền vào một yêu cầu tiếp theo để truy cập vào trang tiếp theo.pageToken
Chỉ định
nextPageToken
từ nội dung phản hồi của trang trước.-
priceLevels
Hạn chế tìm kiếm ở những địa điểm được đánh dấu ở các mức giá nhất định. Chế độ mặc định là chọn tất cả các cấp giá.
Chỉ định một mảng gồm một hoặc nhiều giá trị do
PriceLevel
xác định.Ví dụ:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
Chỉ định cách xếp hạng kết quả trong phản hồi dựa trên loại truy vấn:
- Đối với cụm từ tìm kiếm theo danh mục như "Nhà hàng ở thành phố New York",
RELEVANCE
(xếp hạng kết quả theo mức độ liên quan với nội dung tìm kiếm) là giá trị mặc định. Bạn có thể đặtrankPreference
thànhRELEVANCE
hoặcDISTANCE
(xếp hạng kết quả theo khoảng cách). - Đối với truy vấn không theo danh mục như "Mountain View, CA", bạn nên không đặt
rankPreference
.
- Đối với cụm từ tìm kiếm theo danh mục như "Nhà hàng ở thành phố New York",
regionCode
Mã khu vực 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ự. Tham số này cũng có thể gây ảnh hưởng đến kết quả tìm kiếm. 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 khỏiformattedAddress
. Thông số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm tên quốc gia khi có) hoặcshortFormattedAddress
(không bao giờ bao gồm tên quốc gia).Hầu hết mã CLDR giống hệt với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD 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à cho thực thể "Vương quốc Anh và Bắc Ireland"). Thông số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
strictTypeFiltering
Được dùng với tham số
includedType
. Khi được đặt thànhtrue
, chỉ những địa điểm khớp với các loại đã chỉ định doincludeType
chỉ định mới được trả về. Khi giá trị là false (sai), theo mặc định, phản hồi có thể chứa những địa điểm không khớp với các loại được chỉ định.
Ví dụ về Tìm kiếm bằng văn bản
Tìm địa điểm theo chuỗi truy vấn
Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm bằng văn bản về "Món ăn chay cay ở Sydney, Úc":
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
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,places.formattedAddress
.
Sau đó, phản hồi sẽ có dạng:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "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.types,places.websiteUri
để đưa loại nhà hàng và địa chỉ web vào phản hồi:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -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:searchText'
Phản hồi hiện có dạng:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
Lọc địa điểm theo mức giá
Sử dụng tuỳ chọn priceLevel
để lọc kết quả đến các nhà hàng được xác định là rẻ hoặc đắt vừa phải:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia", "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"] }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
Ví dụ này cũng sử dụng tiêu đề X-Goog-FieldMask
để thêm trường dữ liệu places.priceLevel
vào phản hồi, vì vậy, tiêu đề sẽ có dạng:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
Thêm các tuỳ chọn khác để tinh chỉnh nội dung tìm kiếm, chẳng hạn như includedType
, minRating
, rankPreference
, openNow
và các tham số khác được mô tả trong phần Tham số không bắt buộc.
Giới hạn tìm kiếm trong một khu vực cụ thể
Sử dụng locationRestriction
hoặc locationBias
, nhưng không thể sử dụng cả hai, để giới hạn phạm vi tìm kiếm ở một khu vực. Bạn có thể coi locationRestriction
là chỉ định khu vực chứa kết quả, và locationBias
khi chỉ định khu vực mà kết quả phải ở gần nhưng có thể ở bên ngoài khu vực đó.
Hạn chế khu vực bằng locationRestriction
Dùng tham số locationRestriction
để hạn chế kết quả truy vấn ở một khu vực đã chỉ định. Trong nội dung yêu cầu, hãy chỉ định giá trị vĩ độ và kinh độ low
và high
giúp xác định ranh giới của khu vực.
Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm bằng văn bản về "thực phẩm thuần chay" ở Thành phố New York. Yêu cầu này chỉ trả về 10 kết quả đầu tiên cho các địa điểm đang mở cửa.
curl -X POST -d '{ "textQuery" : "vegetarian food", "pageSize" : "10", "locationRestriction": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } } }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
Chuyển hướng đến một khu vực bằng cách sử dụng locationBias
Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm bằng văn bản về "đồ ăn chay", thiên về một vị trí cách một điểm ở trung tâm San Francisco 500 mét. Yêu cầu này chỉ trả về 10 kết quả đầu tiên cho các địa điểm mở cửa.
curl -X POST -d '{ "textQuery" : "vegetarian food", "openNow": true, "pageSize": 10, "locationBias": { "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' \ 'https://places.googleapis.com/v1/places:searchText'
Tìm bộ sạc xe điện có tốc độ sạc tối thiểu
Sử dụng minimumChargingRateKw
và connectorTypes
để tìm những địa điểm có bộ sạc tương thích với xe điện của bạn.
Ví dụ sau đây cho thấy một yêu cầu về đầu nối sạc xe điện Tesla và J1772 loại 1 với tốc độ sạc tối thiểu là 10 kW ở Mountain View, California. Chỉ có 4 kết quả được trả về.
curl -X POST -d '{ "textQuery": "EV Charging Station Mountain View", "pageSize": 4, "evOptions": { "minimumChargingRateKw": 10, "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"] } }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \ 'https://places.googleapis.com/v1/places:searchText'
Yêu cầu này trả về phản hồi sau:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
Tìm kiếm doanh nghiệp cung cấp dịch vụ tại cơ sở khách hàng
Sử dụng tham số includePureServiceAreaBusinesses
để tìm kiếm các doanh nghiệp không có địa chỉ dịch vụ thực tế (ví dụ: dịch vụ vệ sinh di động hoặc xe bán đồ ăn).
Ví dụ sau đây cho thấy một yêu cầu về thợ sửa ống nước ở San Francisco:
curl -X POST -d '{ "textQuery" : "plumber San Francisco", "includePureServiceAreaBusinesses": true }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
Trong phản hồi, những doanh nghiệp không có địa chỉ dịch vụ thực tế sẽ không bao gồm trường formattedAddress
:
{ "places": [ { "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA", "displayName": { "text": "Advanced Plumbing & Drain", "languageCode": "en" } }, { "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Magic Plumbing Heating & Cooling", "languageCode": "en" } }, /.../ { "displayName": { "text": "Starboy Plumbing Inc.", "languageCode": "en" } }, { "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Cabrillo Plumbing, Heating & Air", "languageCode": "en" } }, { "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA", "displayName": { "text": "Mr. Rooter Plumbing of San Francisco", "languageCode": "en" } }, /.../ { "displayName": { "text": "Pipeline Plumbing", "languageCode": "en" } }, { "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA", "displayName": { "text": "One Source Plumbing and Rooter", "languageCode": "en" } }, /.../ ] }
Chỉ định số kết quả cần trả về trên mỗi trang
Sử dụng tham số pageSize
để chỉ định một số kết quả cần trả về trên mỗi trang. Tham số nextPageToken
trong nội dung phản hồi cung cấp mã thông báo có thể dùng trong các lệnh gọi tiếp theo để truy cập vào trang kết quả tiếp theo.
Ví dụ sau đây cho thấy một yêu cầu về "pizza ở New York" bị giới hạn ở 5 kết quả trên mỗi trang:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5 }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, { "id": "ChIJrXXKn5NZwokR78g0ipCnY60" }, { "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE" }, { "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw" } ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
Để truy cập vào trang kết quả tiếp theo, hãy sử dụng pageToken
để truyền vào nextPageToken
trong phần nội dung yêu cầu:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5, "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, { "id": "ChIJ6ffdpJNZwokRmcafdROM5q0" }, { "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM" }, { "id": "ChIJ8164qwFZwokRhplkmhvq1uE" } ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
Hãy dùng thử!
Trình khám phá API cho phép bạn tạo các yêu cầu mẫu để 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.
Bạn có thể mở rộng phần Hiện các tham số chuẩn và đặt tham số
fields
thành 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 hộp thoại bật lên, hãy chọn tài khoản mà bạn muốn sử dụng để gửi yêu cầu.
Trong bảng điều khiển API Explorer (Trình khám phá API), hãy chọn biểu tượng mở rộng, , để mở rộng cửa sổ API Explorer.