Sau khi có mã địa điểm, bạn có thể yêu cầu thêm chi tiết về một cơ sở cụ thể hoặc địa điểm yêu thích bằng cách bắt đầu một Thông tin chi tiết về địa điểm (Mới) của bạn. Thông tin chi tiết về địa điểm (Mới) yêu cầu 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 từ người dùng và bài đánh giá.
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 để bạn có thể làm quen với API và 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 tham số GET yêu cầu. 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)
Chi tiết địa điểm (Mới) trả về một giá trị đối tượng JSON làm phản hồi. Trong câu trả lời:
- Câu trả lời được thể hiện bằng một
Place
. Đối tượngPlace
chứa thông tin chi tiết về địa điểm. - FieldMask được chuyển trong yêu cầu chỉ định danh sách các trường
đã 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 này bằng cách sử dụng tham số URL
$fields
hoặcfields
hoặc bằng cách sử dụng 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 sẽ không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý không cần thiết và các khoản phí thanh toán.
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 địa điểm trong biểu mẫu:places/PLACE_ID
. 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
,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ề từ mộ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 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 câu trả lời của một Địa điểm chi tiết (Mới), Tìm kiếm lân cận (Mới) và Tìm kiếm văn bản (Mới) yêu cầu, chuỗi này có trong trườngname
của phản hồi. Phiên bản độc lập mã địa điểm có 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 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
, 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 cố gắng hết sức để cung cấp địa chỉ đường phố có thể đọc được cả người dùng và cục bộ. Để đạt được mục tiêu đó, hàm sẽ trả về giá trị đường phố các địa chỉ theo ngôn ngữ địa phương, được chuyển tự thành một tập lệnh có thể đọc được người dùng (nếu cần) quan sát ngôn ngữ ưu tiên. Tất cả giá trị khác được trả về bằng ngôn ngữ ưu tiên. Các thành phần địa chỉ là tất cả được trả về trong cùng một ngôn ngữ, được chọn từ ngôn ngữ đầu tiên thành phần.
- Nếu tên không có sẵn bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả phù hợp nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến nhóm kết quả mà API chọn trả về và thứ tự mà hàm được trả về. Chiến lược phát hành đĩa đơn bộ mã hoá địa lý diễn giải 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ể là có hiệu lực bằng một ngôn ngữ nhưng không có hiệu lực bằng ngôn ngữ khác.
regionCode
Mã vùng dùng để định dạng phản hồi, được chỉ định làm 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ớiregionCode
, mã quốc gia bị bỏ khỏiformattedAddress
. Thông số này không ảnh hưởng đếnadrFormatAddress
, tức là luôn bao gồm quốc gia tên hoặc trênshortFormattedAddress
, mà không bao giờ có tên đó.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à "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "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 tính năng Tự động hoàn thành (Mới) gọi là "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à chọn địa điểm trong tính năng tự động hoàn thành tìm kiếm 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 Chi tiết địa điểm (Mới) những lệnh gọi theo sau lệnh gọi Tự động hoàn thành (Mới). Để biết thêm thông tin, hãy xem 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 cung cấp thông tin chi tiết về một địa điểm bằng cách
placeId
:
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
Hãy 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
để bao gồm
và Plus Code trong
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 thực hiện các yêu cầu mẫu để mà bạn 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) Mở rộng tuỳ chọn Hiển thị các tham số chuẩn rồi đặt
tham số
fields
vào 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 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.