Trang này được dịch bởi Cloud Translation API.

Tìm kiếm văn bản (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

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 doanh nghiệp cũng như đị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ư hai ví dụ đầu tiên trong bảng sau đây có thể trả về kết quả rỗng, 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 độ lệch 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 đó. Lưu ý: Để có kết quả tốt nhất khi tìm kiếm số điện thoại, hãy thêm mã quốc gia, theo sau là dấu cách, rồi đặt tham số `regionCode` tương ứng với mã quốc gia.

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:

Hãy làm thử!

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ượng Place chứa thông tin chi tiết về một địa điểm.
FieldMask được truyền trong yêu cầu 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ặc fields hoặc bằng cách sử dụng tiêu đề HTTP X-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
```
Lưu ý: Không được dùng dấu cách ở bất kỳ vị trí nào trong danh sách trường.

Sử dụng * để truy xuất tất cả các trường.
```
X-Goog-FieldMask: *
```
Ký tự đại diện "*" sẽ chọn tất cả các trường. Tuy nhiên, mặc dù bạn có thể sử dụng ký tự đại diện đó trong quá trình phát triển, nhưng Google không khuyến khích sử dụng mặt nạ trường phản hồi ký tự đại diện (*) trong môi trường sản xuất do lượng lớn dữ liệu có thể được trả về.

Bạn có thể xem thêm hướng dẫn về cách sử dụng places.iconMaskBaseUri và places.iconBackgroundColor trong phần Biểu tượng địa điểm.

Chỉ định một hoặc nhiều trường sau:
- Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (chỉ mã):
  places.attributions, places.id, places.name^*, nextPageToken
  
  ^* Trường places.name chứa tên tài nguyên ở dạng: places/PLACE_ID. Sử dụng places.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.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
  
  ^* Trường places.googleMapsLinks đang ở giai đoạn Bản dùng thử trước khi phát hành công khai và không tính phí, tức là khoản thanh toán là 0 USD đối với việc sử dụng trong giai đoạn Bản dùng thử.
- Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng 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"
Lưu ý: Các giá trị trong Bảng B chỉ được trả về trong phản hồi. Bạn không thể sử dụng các giá trị trong Bảng B làm bộ lọc.
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 được đặt thành false, API sẽ chỉ trả về những doanh nghiệp có địa điểm thực tế.
languageCode

Ngôn 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ợ, vì vậy, danh sách này có thể chưa đầ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ỗi INVALID_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 đó, dịch vụ 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 đượ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 khu vực để 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ặc locationBias, nhưng không được chỉ định cả hai. Hãy coi locationRestriction 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.

Lưu ý: Nếu bạn bỏ qua cả locationBias và locationRestriction, thì theo mặc định, API sẽ sử dụng độ lệch IP. Với tính năng thiên vị IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên vị kết quả.

Lưu ý: Bạn có thể ghi đè tham số locationBias nếu textQuery chứa một vị trí rõ ràng như Market in Barcelona. Trong trường hợp này, locationBias sẽ bị bỏ qua.

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 và điểm cao đại diện cho góc đông bắc của hình chữ nhật.
  
  Khung nhìn được coi là một vùng kín, nghĩa là bao gồm cả ranh giới của vùng đó. 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ì dải 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
    }
  }
}
```
locationRestriction

Chỉ định một khu vực để tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định.

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ặc locationBias, nhưng không được chỉ định cả hai. Hãy coi locationRestriction 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.

Lưu ý: Nếu bạn bỏ qua cả locationBias và locationRestriction, thì theo mặc định, API sẽ sử dụng độ lệch IP. Với tính năng thiên vị IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên vị kết quả.
maxResultCount (không dùng nữa)

Không dùng nữa: Trường này không còn được dùng nữa mà thay vào đó là pageSize. Nếu bạn chỉ định cả maxResultCount và pageSize, thì pageSize sẽ được dùng và maxResultCount sẽ bị bỏ qua.

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ột nextPageToken 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.

Lưu ý: Nếu maxResultCount là 0 hoặc không được chỉ định, thì theo mặc định, API sẽ trả về 20 kết quả trên mỗi trang. Nếu maxResultCount lớn hơn 20, API sẽ trả về không quá 20 kết quả trên mỗi trang.
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ả 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 Places sẽ được trả về nếu bạn đặt thông số này thành false.
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ột nextPageToken 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.

Lưu ý: Nếu pageSize là 0 hoặc không được chỉ định, thì theo mặc định, API sẽ trả về 20 kết quả trên mỗi trang. Nếu pageSize lớn hơn 20, API sẽ trả về không quá 20 kết quả trên mỗi trang.
pageToken

Chỉ định nextPageToken từ phần nội dung phản hồi của trang trước.
priceLevels

Hạn chế kết quả tìm kiếm ở những địa điểm được đánh dấu ở một số 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.

Lưu ý: PRICE_LEVEL_FREE không được phép xuất hiện trong yêu cầu. Phương thức này chỉ được dùng để điền sẵn nội dung phản hồi.

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 của nội dung tìm kiếm) là giá trị mặc định. Bạn có thể đặt rankPreference thành RELEVANCE hoặc DISTANCE (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.
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 ra hiệu ứng thiên vị đối với 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ới regionCode, thì mã quốc gia sẽ bị bỏ qua khỏi formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia khi có) hoặc shortFormattedAddress (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

Dùng với tham số includedType. Khi được đặt thành true, chỉ những địa điểm khớp với các loại đã chỉ định do includeType 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ả cho các nhà hàng được xác định là giá rẻ hoặc giá 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 đề này 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.

Hạn chế tìm kiếm ở 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. Hãy coi locationRestriction là chỉ định khu vực mà kết quả phải nằm trong đó và locationBias là chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

Lưu ý: Khi sử dụng locationRestriction, bạn chỉ có thể chỉ định vùng dưới dạng Khung nhìn hình chữ nhật. Khi sử dụng locationBias, bạn có thể chỉ định vùng dưới dạng Khung nhìn hình chữ nhật hoặc dưới dạng vòng tròn.

Hạn chế khu vực bằng locationRestriction

Sử dụng tham số locationRestriction để giới hạn kết quả truy vấn ở một khu vực cụ thể. Trong phần nội dung yêu cầu, hãy chỉ định các giá trị vĩ độ và kinh độ low và high xác định ranh giới 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 đang 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 những 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ố lượng kết quả trả về trên mỗi trang

Sử dụng tham số pageSize để chỉ định số lượng kết quả sẽ trả về trên mỗi trang. Tham số nextPageToken trong nội dung phản hồi cung cấp một mã thông báo có thể được 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 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 Phần 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.

Tìm kiếm văn bản (Mới)

Yêu cầu Tìm kiếm bằng văn bản

Câu trả lời của tính năng Tìm kiếm văn bản (Mới)

Thông số bắt buộc

FieldMask

textQuery

Thông số tùy chọn

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (không dùng nữa)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering