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

Tìm kiếm văn bản (Mới) 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 một danh sách các vị trí khớp với chuỗi văn bản và mọi độ lệch vị trí đã đặt.

Dịch vụ này đặc biệt hữu ích khi thực hiện các 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 có đị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à địa chỉ hoặc yêu cầu có định dạng kém hoặc yêu cầu bao gồm các thành phần không có đị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 "Đường cao tốc" ở Vương quốc Anh; nhiều "Đường chính" ở Hoa Kỳ. Truy vấn không trả về kết quả mong muốn trừ phi bạn đặt giới hạn về 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 phố.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US"	Chỉ có một "High Street" (Đường cao tốc) trong thành phố Escher của Vương quốc Anh; chỉ có một "Main Street" ở thành phố Pleasanton CA của Hoa Kỳ.
"UniqueRestaurantName New York"	Chỉ có một cơ sở có tên này tại New York; không cần địa chỉ đường phố để phân biệt.
"nhà hàng pizza ở New York"	Truy vấn này có chứa giới hạn về vị trí và "nhà hàng pizza" là một loại địa điểm được xác định rõ. Hàm này trả về nhiều kết quả.
"+1 514-670-8700"	Truy vấn này có chứa số điện thoại. Công cụ 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 trên một số điện thoại, hãy thêm mã quốc gia đứng trước một dấu cách và đặt thông số `regionCode` tương ứng với mã quốc gia.

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ử!

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

Yêu cầu Tìm kiếm văn bản là yêu cầu POST qua HTTP có dạng sau:

https://places.googleapis.com/v1/places:searchText

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 '{
  "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 bằng tính năng Tìm kiếm bằng văn bản (Mới)

Text Search (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ượng Place 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ặc fields hay tiêu đề HTTP X-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
```
Lưu ý: Không được dùng dấu cách ở bất cứ đâu 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 "*" chọn tất cả các trường. Tuy nhiên, mặc dù bạn có thể dùng ký tự đại diện đó trong quá trình phát triển, nhưng Google không khuyến khích việc sử dụng mặt nạ trường phản hồi ký tự đại diện (*) trong phiên bản chính thức vì số 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 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^*
  
  , places.nextPageToken ^* Trường places.name chứa tên tài nguyên ở dạng: places/PLACE_ID. Hãy sử dụng places.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 Tìm kiếm văn bản (Cơ bản):
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.location, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, 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.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 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.servesBeer, places.delivery, places.servesBreakfast, places.servesBreakfast, places.delivery, places.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
textQuery

Chuỗi văn bản cần tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "nơi tốt nhất để ghé thăm ở San Francisco". API trả về các kết quả trùng khớp đề xuất 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 mà người dùng nhận thấy.

Thông số tùy chọn

includedType

Giới hạn kết quả ở các vị trí khớp với loại đã chỉ định trong Bảng A. 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.
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, 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ỗi 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â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ả đị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 một tên không có sẵn bằng ngôn ngữ ưu tiên, 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ề 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ệ ở một ngôn ngữ nhưng lại không hợp lệ ở ngôn ngữ khác.
locationBias

Chỉ định một vùng để tìm kiếm. Vị trí này đóng vai trò là một độ lệch, tức là có thể trả về kết quả liên quan đến vị trí đã chỉ định, bao gồm cả kết quả nằm ngoài khu vực đã chỉ định.

Bạn có thể chỉ định locationRestriction hoặc locationBias, nhưng không thể chỉ định cả hai. Bạn có thể coi locationRestriction là khu vực chỉ định kết quả, còn locationBias dùng để chỉ định khu vực mà kết quả phải ở gần nhưng có thể ở 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 xu hướng IP. Với xu hướng IP, API sẽ sử dụng địa chỉ IP của thiết bị để xu hướng 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 Cửa sổ xem hình chữ nhật hoặc hình tròn.
- Một đường tròn được xác định bởi 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, 0. 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à một khung nhìn vĩ độ – kinh độ, được biểu thị dưới dạng hai đường chéo đối diện điểm thấp và điểm cao. Đ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 độ, còn 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 vượt qua đường kinh độ 180 độ).
  - Nếu low.longitude = -180 độ và high.longitude = 180 độ, khung nhìn sẽ bao gồm tất cả cá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 và không được để trống ô được đại diện. Khung nhìn trống dẫn đến lỗi.
  
  Ví dụ: khung nhìn này bao quanh hoàn toàn 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 vùng để tìm kiếm. Kết quả nằm ngoài khu vực đã chỉ định sẽ không được trả về. Chỉ định khu vực dưới dạng một Khung nhìn hình chữ nhật. Hãy xem nội dung mô tả về locationBias để biết thông tin về cách xác định Khung nhìn.

Bạn có thể chỉ định locationRestriction hoặc locationBias, nhưng không thể chỉ định cả hai. Bạn có thể coi locationRestriction là khu vực chỉ định kết quả, còn locationBias dùng để chỉ định khu vực mà kết quả phải ở gần nhưng có thể ở 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 xu hướng IP. Với xu hướng IP, API sẽ sử dụng địa chỉ IP của thiết bị để xu hướng kết quả.
maxResultCount (không dùng nữa)

Không dùng nữa: Trường này không còn dùng nữa và 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 truy vấn có thể trả về kết quả khác, thì phản hồi sẽ bao gồm nextPageToken mà bạn có thể truyền vào yêu cầu tiếp theo để truy cập vào trang tiếp theo.

Lưu ý: Nếu maxResultCount bằng 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 và tốc độ sạc có sẵn cho xe điện (EV).
- connectorTypes
  
  Các bộ lọc theo loại giắc cắm sạc xe điện có sẵn tại một địa điểm. Địa điểm không hỗ trợ bất kỳ loại trình kết nối nào sẽ bị lọc ra. Các loại giắc cắm 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 (để sạc nhanh cho 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
  
  Các bộ lọc đặt theo công suất sạc xe điện tối thiểu tính bằng kilowatt (kW). Những địa điểm có mức phí thấp hơn mức tính phí tối thiểu sẽ được lọc ra. Ví dụ: để tìm trạm sạc xe điện có công suất sạc tối thiểu là 10 kW, bạn có thể đặt thông số này thành "10".
minRating

Chỉ cung cấp kết quả cho những người dùng có điểm xếp hạng trung bình của người dùng lớn hơn hoặc bằng giới hạn này. Giá trị phải nằm trong khoảng từ 0 đến 5 (bao gồm) và tăng từng 0,5. Ví dụ: bao gồm 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ỏ mọi kết quả có điểm xếp hạng nhỏ hơn 1.
openNow

Nếu là true, hãy 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à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 truy vấn có thể trả về kết quả khác, thì phản hồi sẽ bao gồm nextPageToken mà bạn có thể truyền vào yêu cầu tiếp theo để truy cập vào trang tiếp theo.

Lưu ý: Nếu pageSize bằng 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ừ 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. Lựa chọn mặc định là chọn tất cả các mức 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 trong yêu cầu. Trường này chỉ được dùng để điền câu trả lờ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 cụm từ tìm kiếm:
- Đối với cụm từ tìm kiếm theo danh mục, chẳng hạn 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 cụm từ 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 cụm từ tìm kiếm không theo danh mục như "Mountain View, CA", bạn không nên đặt rankPreference.
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ự. 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ới regionCode, thì mã quốc gia sẽ bị bỏ qua trong formattedAddress. Tham số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia nếu có) hoặc trên shortFormattedAddress (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ả.
strictTypeFiltering

Được dùng với tham số includedType. Khi bạn đặt thành true, chỉ những vị trí khớp với các kiểu đã chỉ định do includeType chỉ định mới được trả về. Khi đặt là false, theo mặc định, phản hồi có thể chứa các vị trí không khớp với loại đã chỉ định.

Ví dụ về Tìm kiếm 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 văn bản cho "Đồ ăn chay cay nồng ở 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'

Câu trả lờ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 để có dạng như sau:

{
  "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 lựa chọn bổ sung để tinh chỉnh kết quả 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.

Tìm địa điểm trong một khu vực

Sử dụng locationRestriction hoặc locationBias (nhưng không được dùng cả hai) để hạn chế tìm kiếm trong 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 đó.

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

Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm văn bản cho "Đồ ăn chay cay nồng" có xu hướng nằm trong phạm vi 500 mét xung quanh một điểm ở trung tâm thành phố San Francisco. 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" : "Spicy 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 yêu cầu đối với đầu nối sạc xe điện loại 1 của Tesla và J1772 với công suất sạc tối thiểu là 10 kW ở Mountain View, CA. Chỉ trả về 4 kết quả.

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
          }
        ]
      }
    }
  ]
}

Chỉ định số lượng kết quả để trả về cho mỗi trang

Sử dụng tham số pageSize để chỉ định một số kết quả cần trả về cho 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 đối với "pizza ở New York" có tối đa 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 để chuyển nextPageToken vào 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ử!

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 hộp thoại bật lên, hãy chọn tài khoản bạn muốn sử dụng để đưa ra 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.

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

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

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

Thông số bắt buộc

FieldMask

textQuery

Thông số tùy chọn

includedType

languageCode

locationBias

locationRestriction

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

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering