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 danh sách các địa điểm khớp với chuỗi văn bản và mọi độ lệch vị trí đã được đặt.

Dịch vụ này đặc biệt hữu ích khi thực hiện truy vấn địa chỉ không rõ ràng trong một hệ thống tự động, và các thành phần không phải địa chỉ của chuỗi có thể khớp với cả doanh nghiệp và địa chỉ. Ví dụ về truy vấn địa chỉ không rõ ràng là các địa chỉ hoặc yêu cầu có định dạng không chuẩn, bao gồm các thành phần không phải địa chỉ như tên doanh nghiệp. Các yêu cầu như 2 ví dụ đầu tiên trong bảng sau đây có thể trả về kết quả bằng 0 trừ phi bạn đặt một vị trí (chẳng hạn như khu vực, hạn chế về vị trí hoặc sai lệch về vị trí).

"10 High Street, UK" hoặc "123 Main Street, US" Nhiều "Đườ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.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US" Chỉ có một "High Street" (Phố cao) 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 ở 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 đó.

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 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 (Mặt nạ trường) được chuyển trong yêu cầu sẽ chỉ định danh sách các trường được trả về trong đối tượng Place.

Đối tượng JSON hoàn chỉnh có dạng:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Thông số bắt buộc

  • FieldMask

    Chỉ định danh sách các trường cần trả về trong phản hồi bằng cách tạo mặt nạ trường phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tham số URL $fields hoặ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 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.

    Việc che trường là một phương pháp thiết kế hay để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và các khoản phí không cần thiết.

    Chỉ định danh sách các loại dữ liệu địa điểm được phân tách bằng dấu phẩy để trả về. Ví dụ: để truy xuất tên hiển thị và địa chỉ của địa điểm.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Sử dụng * để truy xuất tất cả các trường.

    X-Goog-FieldMask: *

    Chỉ định một hoặc nhiều trường sau:

    • Các trường sau đây 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 Bản dùng thử.

    • Các trường sau đây kích hoạt SKU Tìm kiếm văn bản (Nâng cao):

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

    • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (Ưu tiên):

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.routingSummaries,* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

      * Chỉ tìm kiếm bằng văn bản và tìm kiếm xung quanh

  • textQuery

    Chuỗi văn bản để tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "địa điểm tham quan tốt nhất ở San Francisco". API này trả về các kết quả trùng khớp dựa trên chuỗi này và sắp xếp các kết quả dựa trên mức độ liên quan được nhận thấy.

Thông số tùy chọn

  • includedType

    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"

  • includePureServiceAreaBusinesses

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

  • languageCode

    Ngôn ngữ dùng để trả về kết quả.

    • Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, 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 đó, API này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc được nếu cần, tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
    • Nếu 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ả đó. 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 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.

    Chỉ định khu vực dưới dạng Cửa sổ xem hình chữ nhật hoặc hình 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 và không được để trống ô được đại diện. 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 này dưới dạng 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. 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.

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

    Chỉ định số lượng kết quả (từ 1 đến 20) hiển thị trên mỗi trang. Ví dụ: việc đặt giá trị maxResultCount là 5 sẽ trả về tối đa 5 kết quả trên trang đầu tiên. Nếu có nhiều kết quả hơn có thể được trả về từ truy vấn, thì phản hồi sẽ bao gồm mộ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.

  • 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). 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 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 (bao gồm) và tăng 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 Đị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 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.

  • 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.

    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. 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 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 (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 đượ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'

Câu trả lời hiện có trong biểu mẫu:

{
  "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 để 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 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.

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. 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 nằm gần nhưng có thể nằm bên ngoà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ề "Đồ ăn chay cay", ưu tiên vị trí cách một điểm ở trung tâm thành phố 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" : "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 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 thông số includePureServiceAreaBusinesses để tìm kiếm các doanh nghiệp không có địa chỉ dịch vụ thực (ví dụ: dịch vụ vệ sinh lưu động hoặc xe bán đồ ăn).

Ví dụ sau đây thể hiện một yêu cầu về dịch vụ sửa ống nước ở San Francisco:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Trong phản hồi, những doanh nghiệp không có địa chỉ dịch vụ thực tế sẽ không bao gồm trường formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

Chỉ định số kết quả cần trả về trên mỗi trang

Sử dụng tham số pageSize để chỉ định một số kết quả cần trả về trên mỗi trang. Tham số nextPageToken trong nội dung phản hồi cung cấp mã thông báo có thể dùng trong các lệnh gọi tiếp theo để truy cập vào trang kết quả tiếp theo.

Ví dụ sau đây cho thấy một yêu cầu về "pizza ở New York" bị giới hạn ở 5 kết quả trên mỗi trang:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Để truy cập vào trang kết quả tiếp theo, hãy sử dụng pageToken để truyền vào nextPageToken trong phần nội dung yêu cầu:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Hãy dùng thử!

Trình khám phá API cho phép bạn tạo các yêu cầu mẫu để bạn có thể làm quen với API và các tuỳ chọn API.

  1. Chọn biểu tượng API Mở rộng Trình khám phá API. ở bên phải của trang.

  2. 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.

  3. Chỉnh sửa Phần nội dung yêu cầu (không bắt buộc).

  4. 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.

  5. 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 Trình khám phá API., để mở rộng cửa sổ API Explorer.