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 bắt đầu yêu cầu Thông tin chi tiết về địa điểm (Mới). Yêu cầu Chi tiết địa điểm (Mới) sẽ trả về thông tin toàn diện 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:
- Tìm kiếm văn bản (Mới) hoặc Tìm kiếm lân cận (Mới)
- API mã hoá địa lý
- API Tuyến đường
- API Xác thực địa chỉ
- Tự động hoàn thành địa điểm
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 Chi tiết địa điểm (Mới)
Yêu cầu Chi tiết địa điểm là yêu cầu HTTP GET trong biểu mẫu:
https://places.googleapis.com/v1/places/PLACE_ID
Truyền tất cả tham số dưới dạng tham số URL hoặc trong tiêu đề dưới dạng 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 chi tiết về địa điểm (Mới)
Place Details (Mới) sẽ 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ượngPlace
chứa thông tin chi tiết về đị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:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
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ặcfields
hay tiêu đề HTTPX-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: 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):
attributions
,id
,name
*,photos
* Trườngname
chứa tên tài nguyên ở dạng:places/PLACE_ID
.
Hãy sử dụngdisplayName
để 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 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
Các trường sau đây 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
,servesBreakfast
,servesBreakfast
,delivery
,servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
-
placeId
Giá trị nhận dạng dạng văn bản giúp xác định duy nhất một địa điểm, được trả về qua tính năng 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 nội dung tổng quan về mã địa điểm.
Chuỗi
places/PLACE_ID
còn được gọi là tên tài nguyên địa điểm. Trong phản hồi cho yêu cầu về 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ườngname
của phản hồi. Mã địa điểm độc lập nằm trong trườngid
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 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
, thì 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ỗiINVALID_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.
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ự. 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ớiregionCode
, thì mã quốc gia sẽ bị bỏ qua trongformattedAddress
. Thông số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm tên quốc gia) hoặc trênshortFormattedAddress
(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ả.
-
sessionToken
Mã thông báo phiên là các chuỗi do người dùng tạo để theo dõi lệnh gọi Tự động hoàn thành (Mới) dưới dạng "phiên". Tính năng Tự động hoàn thành (Mới) sử dụng mã thông báo phiên để nhóm các giai đoạn truy vấn và lựa chọn địa điểm trong lượt tìm kiếm tự động hoàn thành của người dùng thành 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 phần 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
cung cấp 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 để trả về thông tin bổ sung.
Ví dụ: thêm formattedAddress,plusCode
để đưa địa chỉ và Plus Code vào phản hồ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
Câu trả lờ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 đư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.
Cách gửi yêu cầu:
- Chọn biểu tượng API ở bên phải của trang.
- Đặt tham số
name
thành:places/PLACE_ID
(không bắt buộc) - (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ọ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 để tạo 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.