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

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Giới thiệu

Tìm kiếm bằng 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 sẽ phản hồi bằng một danh sách các địa điểm khớp với chuỗi văn bản và mọi thông tin thiên vị về vị trí đã được đặ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 phải địa chỉ của chuỗi cũng có thể khớp với các doanh nghiệp cũng như địa chỉ. Ví dụ về các cụm từ tìm kiếm địa chỉ không rõ ràng là địa chỉ có định dạng không chính xác hoặc yêu cầu có chứa các thành phần không phải địa chỉ, chẳng hạn như tên doanh nghiệp. Các yêu cầu như hai ví dụ đầu tiên trong bảng sau có thể không trả về kết quả nào, 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" (10 High Street, Vương quốc Anh) hoặc "123 Main Street, US" (123 Main Street, Hoa Kỳ)	Nhiều "High Street" ở Vương quốc Anh; nhiều "Main Street" ở Hoa Kỳ. Cụm từ tìm kiếm không trả về kết quả mong muốn trừ phi bạn đặt một chế độ hạn chế về vị trí.
"ChainRestaurant New York"	Nhiều vị trí "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" ở thành phố Escher của Vương quốc Anh; chỉ có một "Main Street" ở 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ố để phân biệt.
"nhà hàng pizza ở New York"	Cụm từ tìm kiếm này có 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õ. Hàm này trả về nhiều kết quả.
"+1 514-670-8700"	Cụm từ tìm kiếm này có chứa số điện thoại. Hàm này trả về nhiều kết quả cho những địa điểm được 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 số điện thoại, hãy thêm mã quốc gia, sau đó là một khoảng trắng và đặt tham số `regionCode` tương ứng với mã quốc gia. Định dạng số điện thoại khác nhau tuỳ theo quốc gia và API sẽ cố gắng trả về kết quả cho những định dạng này.

APIs Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để có thể làm quen với API và các lựa chọn API:

Hãy làm thử!

Yêu cầu Tìm kiếm bằng văn bản (Mới)

Yêu cầu Tìm kiếm văn bản (mới) là một yêu cầu HTTP POST có dạng như sau:

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

Truyền tất cả cá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 '{
  "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 bằng 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ả 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 duy nhất.
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 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.

Che phủ 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à phí thanh toán không cần thiết.

Chỉ định danh sách các loại dữ liệu về đị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 "*" 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 bạn sử dụng mặt nạ trường phản hồi ký tự đại diện (*) trong quá trình sản xuất vì có thể trả về một lượng lớn dữ liệu.

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 Text Search Essentials ID Only SKU:
  places.attributions
  places.id
  places.name^*
  nextPageToken
  
  ^* Trường places.name chứa tên tài nguyên của địa điểm ở dạng: places/PLACE_ID. Sử dụng places.displayName trong SKU Pro để 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 Tìm kiếm văn bản chuyên nghiệp:
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  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.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* Mô tả địa chỉ thường được cung cấp cho khách hàng ở Ấn Độ và đang trong giai đoạn thử nghiệm ở những nơi khác.
  
  ^** Trường places.googleMapsLinks đang ở giai đoạn Xem trước trước giai đoạn phát hành rộng rãi và không tính phí, tức là mức phí là 0 USD cho việc sử dụng trong giai đoạn Xem trước.
- Các trường sau đây kích hoạt SKU Tìm kiếm văn bản dành cho doanh nghiệp:
  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 Text Search Enterprise + Atmosphere:
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  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ỉ có tính năng Tìm kiếm bằng văn bản và Tìm kiếm lân cận
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 đẹp nhất ở San Francisco". API này trả về các kết quả khớp có thể 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 cảm nhận được.

Thông số tùy chọn

includedType

Thiên vị kết quả đối với những địa điểm phù hợ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.

Tính năng Tìm kiếm bằng văn bản (Mới) áp dụng bộ lọc theo loại cho một số cụm từ tìm kiếm, tuỳ thuộc vào khả năng áp dụng. Ví dụ: bộ lọc theo loại có thể không được áp dụng cho các cụm từ tìm kiếm về địa chỉ cụ thể ("123 Main Street"), nhưng bộ lọc theo loại hầu như luôn được áp dụng cho các cụm từ tìm kiếm theo danh mục ("cửa hàng gần đây" hoặc "trung tâm mua sắm").

Để áp dụng tính năng lọc theo loại cho tất cả các truy vấn, hãy đặt strictTypeFiltering thành true.
includePureServiceAreaBusinesses

Nếu được đặt thành true, phản hồi sẽ bao gồm những doanh nghiệp đến gặp hoặc giao hàng trực tiếp cho khách hàng, nhưng không có địa điểm kinh doanh thực tế. Nếu bạn đặt thành false, API sẽ chỉ trả về những doanh nghiệp có địa điểm kinh doanh thực tế.
languageCode

Ngôn ngữ mà bạn muốn nhận 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ột 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 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 sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản 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ả các địa chỉ khác đều đượ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 không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả trùng 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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho 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à một thiên kiến, tức 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 khu vực mà kết quả phải nằm trong đó, còn locationBias là chỉ định khu vực mà kết quả có khả năng nằm trong hoặc gần đó nhưng có thể nằm 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 tính năng thiên vị 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, chẳng hạn 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 dưới dạng hình tròn.
- Một hình 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,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 hiển thị vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm thấp và cao đối diện 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.
  
  Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):
  - Nếu low = high, khung nhìn sẽ bao gồm đ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 độ, thì 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, đồng thời hộp được biểu thị không được trống. Khung hiển thị trống sẽ gây ra lỗi.
  
  Ví dụ: khung hiển thị này bao trọ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 khu vực để tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về.

Chỉ định khu vực dưới dạng một Khung hiển thị 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 khu vực mà kết quả phải nằm trong đó, còn locationBias là chỉ định khu vực mà kết quả có khả năng nằm trong hoặc gần đó nhưng có thể nằm 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 tính năng thiên vị 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 dùng nữa mà thay bằng 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) sẽ 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ả 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, 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 xe điện (EV) hiện có và tốc độ sạc.
- connectorTypes
  
  Lọc theo loại giắc cắm sạc xe điện có tại một địa điểm. Một địa điểm không hỗ trợ bất kỳ loại giắc cắm 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ủ tiêu chuẩn GB/T (để 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.
  - Để lọc kết quả cho một trình kết nối cụ thể được hỗ trợ, hãy đặt connectorTypes thành giá trị đó. Ví dụ: để tìm giắc cắm loại 1 J1772, hãy đặt connectorTypes thành EV_CONNECTOR_TYPE_J1772.
  - Để lọc kết quả cho các trình kết nối không được hỗ trợ, hãy đặt connectorTypes thành EV_CONNECTOR_TYPE_OTHER.
  - Để lọc kết quả cho bất kỳ loại giắc cắm nào là ổ cắm trên tường, hãy đặt connectorTypes thành EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
  - Để lọc kết quả cho bất kỳ loại trình kết nối nào, hãy đặt connectorTypes thành EV_CONNECTOR_TYPE_UNSPECIFIED hoặc không đặt giá trị cho connectorTypes.
- minimumChargingRateKw
  
  Lọc các địa điểm theo tốc độ sạc tối thiểu cho xe điện tính bằng kilowatt (kW). Mọi địa điểm có mức sạc thấp hơn mức sạc tối thiểu đều 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 kết quả 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,0 đến 5,0 (tính toàn bộ) theo mức tăng 0,5. Ví dụ: 0, 0,5, 1,0, ..., 5,0 (bao gồm). 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 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 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 tham số này thành false.
pageSize

Chỉ định số lượng kết quả (từ 1 đến 20) sẽ 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ả 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, 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 ở một số mức giá nhất định. Theo mặc định, tất cả các mức giá đều được chọn.

Bạn có thể dự kiến mức giá cho những địa điểm thuộc các loại sau:
Những địa điểm thuộc loại không được hỗ trợ sẽ không có trong phản hồi nếu bạn chỉ định priceLevels.

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"]
```
Lưu ý: PRICE_LEVEL_FREE không được phép có trong yêu cầu. Tham số này chỉ được dùng để điền sẵn câu trả lời.
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 một 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 cụm từ tìm kiếm) là chế độ 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 một cụm từ tìm kiếm không theo danh mục, chẳng hạn như "Mountain View, CA", bạn nên để rankPreference chưa đặt.
regionCode

Mã khu vực dùng để định dạng phản hồi, được chỉ định là giá trị mã CLDR gồm 2 ký tự. Tham số này cũng có thể có 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 trong formattedAddress. Tham số này không có hiệu lực trên adrFormatAddress. Tham số này luôn bao gồm tên quốc gia (nếu có) hoặc trên shortFormattedAddress. Tham số này không bao giờ bao gồm tên quốc gia.

Hầu hết mã CLDR đều giống với mã ISO 3166-1, 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 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "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.
strictTypeFiltering

Được 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 được chỉ định do includeType chỉ định mới được trả về. Khi giá trị là false (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ính năng Tìm kiếm bằng văn bản (Mới)

Tìm một địa điểm bằng chuỗi truy vấn

Ví dụ sau đây minh hoạ một yêu cầu Tìm kiếm bằng văn bản (Mới) cho "Đồ ă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 nhiều loại dữ liệu hơn 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 lựa chọn priceLevel để lọc kết quả theo những nhà hàng được xác định là có 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 để 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 lựa 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 trong một khu vực cụ thể

Sử dụng locationRestriction hoặc locationBias (nhưng không sử dụng cả hai) để hạn chế tìm kiếm trong một khu vực. Hãy coi locationRestriction là việc chỉ định khu vực mà kết quả phải nằm trong, còn locationBias là việc 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 khu vực dưới dạng khung nhìn hình chữ nhật. Khi sử dụng locationBias, bạn có thể chỉ định khu vực dưới dạng khung hiển thị hình chữ nhật hoặc dưới dạng hình 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 trong một khu vực cụ thể. Trong 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 (Mới) cho "thực phẩm chay" ở Thành phố New York. Yêu cầu này chỉ trả về 10 kết quả đầu tiên cho những đị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'

Thiên vị cho 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 (Mới) cho "thực phẩm chay" được điều chỉnh theo một vị trí trong vòng 500 mét tính từ một điểm ở trung tâm San Francisco. Yêu cầu này chỉ trả về 10 kết quả đầu tiên cho những đị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ề bộ sạc xe điện loại 1 của Tesla và J1772 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 phục vụ tận nơi

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 ở Đà Nẵng:

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 có 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ả sẽ trả về trên mỗi trang

Sử dụng tham số pageSize để chỉ định số lượng 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ột 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" 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 dùng pageToken để truyền vào nextPageToken trong 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"
}

Nhận nội dung mô tả địa chỉ

Mã mô tả địa chỉ cung cấp thông tin liên quan về vị trí của một địa điểm, bao gồm cả các địa danh lân cận và các khu vực chứa địa điểm đó.

Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm bằng văn bản (Mới) cho các địa điểm gần một trung tâm mua sắm ở San Jose. Trong ví dụ này, bạn thêm addressDescriptors vào mặt nạ trường:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

Phản hồi bao gồm địa điểm được chỉ định trong yêu cầu, danh sách các địa danh lân cận và khoảng cách của các địa danh đó so với địa điểm, cũng như danh sách các khu vực và mối quan hệ bao hàm của các khu vực đó với địa điểm:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

Hãy dùng thử!

APIs 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 lựa chọn API.

Chọn biểu tượng API api ở bên phải trang.
Bạn có thể chỉnh sửa các tham số yêu cầu (không bắt buộc).
Chọn nút Thực thi. Trong hộp thoại, hãy chọn tài khoản mà bạn muốn dùng để đưa ra yêu cầu.
Trong bảng điều khiển APIs Explorer, hãy chọn biểu tượng toàn màn hình fullscreen để mở rộng cửa sổ APIs Explorer.

Tìm kiếm văn bản (Mới) Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giới thiệu

Yêu cầu Tìm kiếm bằng văn bản (Mới)

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