Chi tiết địa điểm (Mới)

Sau khi có mã địa điểm, bạn có thể yêu cầu thêm thông tin chi tiết về một cơ sở hoặc địa điểm yêu thích cụ thể bằng cách tạo yêu cầu Thông tin chi tiết về địa điểm (Mới). Yêu cầu Thông tin chi tiết về địa điểm (Mới) trả về thông tin đầy đủ hơn về địa điểm được chỉ định, chẳng hạn như địa chỉ đầy đủ, số điện thoại, điểm xếp hạng và bài đánh giá của người dùng.

Có nhiều cách để lấy mã địa điểm. Bạn có thể sử dụng:

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

Hãy làm thử!

Yêu cầu Thông tin chi tiết về địa điểm (Mới)

Yêu cầu Thông tin chi tiết về địa điểm là một yêu cầu HTTP GET trong biểu mẫu:

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

Truyền tất cả các tham số dưới dạng tham số URL hoặc đưa vào tiêu đề như một phần của yêu cầu GET. Ví dụ:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

Hoặc trong lệnh cURL:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Câu trả lời cho Thông tin về địa điểm (Mới)

Thông tin chi tiết về địa điểm (Mới) trả về một đối tượng JSON làm phản hồi. Trong câu trả lời:

  • Phản hồi đượ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ề địa điểm.
  • FieldMask (Mặt nạ) được truyền vào 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:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

Thông số bắt buộc

  • FieldMask

    Chỉ định danh sách 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 hay fields, hoặc bằng tiêu đề HTTP X-Goog-FieldMask. Không có danh sách mặc định các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường (field mask), phương thức sẽ trả về một lỗi.

    Che giấu trường là một phương pháp thiết kế hay để đảm bảo 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 địa điểm cần trả về, được phân tách bằng dấu phẩy. Ví dụ: để truy xuất tên hiển thị và địa chỉ của địa điểm.

    X-Goog-FieldMask: displayName,formattedAddress

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

    X-Goog-FieldMask: *

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

    • Các trường sau đây kích hoạt SKU Thông tin chi tiết về địa điểm (Chỉ mã nhận dạng):

      id, name*, photos

      * Trường name chứa tên tài nguyên của địa điểm ở dạng: places/PLACE_ID. Sử dụng displayName để 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 Thông tin chi tiết về địa điểm (Chỉ vị trí):

      addressComponents, adrFormatAddress, formattedAddress, location, plusCode, shortFormattedAddress, types, viewport

    • Các trường sau đây kích hoạt SKU Thông tin chi tiết về địa điểm (Cơ bản):

      accessibilityOptions, businessStatus, displayName, googleMapsUri, iconBackgroundColor, iconMaskBaseUri, primaryType, primaryTypeDisplayName, subDestinations, utcOffsetMinutes

    • Các trường sau đây kích hoạt SKU Thông tin chi tiết về địa điểm (Nâng cao):

      currentOpeningHours, currentSecondaryOpeningHours, internationalPhoneNumber, nationalPhoneNumber, priceLevel, rating, regularOpeningHours, regularSecondaryOpeningHours, userRatingCount, websiteUri

    • Sau đây là các trường kích hoạt SKU Thông tin chi tiết về địa điểm (ưu tiên):

      allowsDogs, curbsidePickup, delivery, dineIn, editorialSummary, evChargeOptions, fuelOptions, goodForChildren, goodForGroups, goodForWatchingSports, liveMusic, menuForChildren, parkingOptions, paymentOptions, outdoorSeating, reservable, restroom, reviews, servesBeer, delivery, delivery, delivery, delivery, delivery, delivery, delivery, delivery, delivery, delivery, delivery, servesBeer, delivery, menuForChildren, menuForChildrenservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout

  • placeId

    Giá trị nhận dạng dạng văn bản xác định duy nhất một địa điểm, được trả về từ Tìm kiếm văn bản (Mới) hoặc Tìm kiếm lân cận (Mới). Để biết thêm thông tin về mã địa điểm, hãy xem bài viết tổng quan về mã địa điểm.

    Chuỗi places/PLACE_ID còn được gọi là địa điểm tên tài nguyên. Trong phản hồi cho các yêu cầu Thông tin chi tiết về địa điểm (Mới), Tìm kiếm lân cận (Mới) và Tìm kiếm văn bản (Mới), chuỗi này nằm trong trường name của phản hồi. Mã địa điểm độc lập nằm trong trường id của phản hồi.

Thông số tùy chọn

  • languageCode

    Ngôn ngữ mà kết quả trả về.

    • Xem danh sách ngôn ngữ được hỗ trợ. Google thường cập nhật các ngôn ngữ được hỗ trợ nên danh sách này có thể chưa đầ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 sẽ cố gắng hết sức để cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương mà người dùng và người dân địa phương có thể đọc được. Để đạt được mục tiêu đó, phương thức 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, đồng thời quan sát 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 tên không được hỗ trợ bằng ngôn ngữ ưu tiên, thì 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ề, cũng như thứ tự mà các kết quả được trả về. Bộ mã hoá địa lý này diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như cách viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác.
  • regionCode

    Mã vùng 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ự. 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ị loại khỏi formattedAddress. Tham số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia) hoặc đối với shortFormattedAddress (không bao giờ bao gồm tên quốc gia).

    Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, 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 là "gb" (về mặt kỹ thuật, là pháp nhân của "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.

  • sessionToken

    Mã thông báo phiên là các chuỗi do người dùng tạo, theo dõi các lệnh gọi Tự động hoàn thành (Mới) dưới dạng "phiên hoạt động". Tính năng Tự động hoàn thành (Mới) sử dụng mã phiên để nhóm các giai đoạn truy vấn và lựa chọn vị trí của nội dung tìm kiếm tự động hoàn thành của người dùng vào một phiên riêng biệt cho mục đích thanh toán. Mã thông báo phiên được chuyển vào các lệnh gọi Chi tiết địa điểm (Mới) theo sau các lệnh gọi Tự động hoàn thành (Mới). Để biết thêm thông tin, hãy xem bài viết Mã thông báo phiên.

Ví dụ về Thông tin chi tiết về địa điểm

Ví dụ sau đây yêu cầu placeId thông tin chi tiết về một địa điểm:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

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: id,displayName. Sau đó, phản hồi sẽ có dạng:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Thêm các loại dữ liệu khác vào mặt nạ trường (field mask) để trả về thông tin bổ sung. Ví dụ: thêm formattedAddress,plusCode để đưa địa chỉ và Plus Code vào câu trả lời:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Phản hồi hiện có dạng:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Hãy dùng thử!

API Explorer cho phép bạn thực hiện các yêu cầu mẫu để bạn có thể làm quen với các API và các tuỳ chọn API.

Cách gửi yêu cầu:

  1. Đặt tham số name (không bắt buộc) thành:
    places/PLACE_ID
  2. (Không bắt buộc) Mở rộng mục Show standard parameters (Hiện thông số chuẩn) và đặt tham số fields thành field mask (mặt nạ trường).
  3. Chọn nút Thực thi. Trong cửa sổ bật lên, hãy chọn tài khoản mà bạn muốn dùng để thực hiện yêu cầu.