簡介
取得地點 ID 後,您可以發出 Place Details (新版) 要求,取得特定商家或搜尋點的詳細資料。Place Details (新版) 要求會傳回指定地點更全面的資訊,例如完整地址、電話號碼、使用者評分和評論。
取得地點 ID 的方法有很多種。例如:
- Text Search (新版) 或 Nearby Search (新版)
- Geocoding API
- Routes API
- Address Validation API
- Autocomplete (新版)
APIs Explorer 可讓您傳送即時要求,熟悉 API 和 API 選項:
Place Details (新版) 要求
Place Details (新版) 要求是 HTTP GET 要求,格式如下:
https://places.googleapis.com/v1/places/PLACE_ID
以網址參數或標頭的形式,將所有參數做為 GET 要求的一部分傳遞。例如:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY或在 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
Place Details (新版) 回應
Place Details (新版) 會 以 JSON 物件的形式傳回回應。在回應中:
完整的 JSON 物件格式如下:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
必要參數
-
FieldMask
建立回應欄位遮罩,指定要在回應中傳回的欄位清單。使用網址參數
$fields或fields,或使用 HTTP 標頭X-Goog-FieldMask,將回應欄位遮罩傳遞至方法。回應中沒有預設的傳回欄位清單。 如果省略欄位遮罩,方法會傳回錯誤。欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,有助於避免不必要的處理時間和帳單費用。
指定要傳回的地點資料類型清單,並以半形逗號分隔。例如,擷取地點的顯示名稱和地址。
X-Goog-FieldMask: displayName,formattedAddress
使用
*擷取所有欄位。X-Goog-FieldMask: *
指定下列一或多個欄位:
下列欄位會觸發 Place Details Essentials IDs Only SKU:
attributions
consumerAlert
id
movedPlace
movedPlaceId
name*
photos
*
name欄位包含地點資源名稱,格式為:places/PLACE_ID。如要取得地點的文字名稱,請在 Pro SKU 中要求displayName欄位。如需欄位和相關 SKU 的完整清單,請參閱「地點資料欄位 (新版)」。
下列欄位會觸發 Place Details Essentials SKU:
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* 地址描述元已在印度正式發布,其他地區則為實驗功能。
如需欄位和相關 SKU 的完整清單,請參閱「地點資料欄位 (新版)」。
下列欄位會觸發 Place Details Pro SKU:
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsTypeLabel
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
如需欄位和相關 SKU 的完整清單,請參閱「地點資料欄位 (新版)」。
下列欄位會觸發 Place Details Enterprise SKU:
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUri如需欄位和相關 SKU 的完整清單,請參閱「地點資料欄位 (新版)」。
下列欄位會觸發 Place Details Enterprise + Atmosphere SKU:
allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries*
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
* 僅限 Text Search 和 Nearby Search如需欄位和相關 SKU 的完整清單,請參閱「地點資料欄位 (新版)」。
-
placeId
用來識別特定地點的文字 ID,由 Text Search (新版) 或 Nearby Search (新版) 傳回。如要進一步瞭解地點 ID,請參閱地點 ID 總覽。
字串
places/PLACE_ID也稱為地點資源名稱。在 Place Details (新版)、Nearby Search (新版) 和 Text Search (新版) 要求的傳回結果中,這個字串會包含在回應的name欄位中。獨立地點 ID 包含在回應的id欄位中。
選用參數
languageCode
傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言,因此這份清單可能不完整。
-
如未提供
languageCode,API 預設為en。如果指定的語言代碼無效,API 會傳回INVALID_ARGUMENT錯誤。 - API 會盡可能提供使用者和當地人都能看懂的街道地址。為達成這個目標,系統會以當地語言傳回街道地址,並視需要按照偏好語言,將地址音譯為使用者可閱讀的文字。所有其他地址都會以偏好語言傳回。系統會以相同語言傳回所有地址元件,而該語言是從第一個元件中選擇。
- 如果沒有偏好語言的名稱,API 會使用最接近的相符項目。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言以不同方式解讀縮寫,例如街道類型的縮寫,或可能在某種語言中有效,但在另一種語言中無效的同義詞。
regionCode
用於設定回應格式的區碼,指定為 雙字元 CLDR 代碼值。沒有預設值。
如果回應中
formattedAddress欄位的國家/地區名稱與regionCode相符,則formattedAddress會省略國家/地區代碼。這個參數對adrFormatAddress(一律包含國家/地區名稱) 或shortFormattedAddress(一律不含國家/地區名稱) 沒有影響。大多數 CLDR 代碼與 ISO 3166-1 代碼相同,但有一些需要注意的例外情況。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而 ISO 3166-1 代碼則是「gb」(技術上代表「大不列顛暨北愛爾蘭聯合王國」)。這項參數可能會根據適用法律影響結果。
-
sessionToken
工作階段符記是使用者產生的字串,可將 Autocomplete (New) 呼叫追蹤為「工作階段」。Autocomplete (新版) 會使用工作階段符記,將使用者自動完成搜尋的查詢和地點選取階段歸入不同的工作階段,以用於計費。工作階段權杖會傳遞至 Autocomplete (新版) 呼叫之後的 Place Details (新版) 呼叫。詳情請參閱「工作階段符記」。
Place Details (新版) 範例
以下範例會依 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
請注意,X-Goog-FieldMask 標頭會指定回應包含下列資料欄位:id,displayName。回應格式如下:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
在欄位遮罩中加入更多資料類型,即可傳回其他資訊。舉例來說,新增 formattedAddress,plusCode 即可在回應中加入地址和 Plus Code:
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
回應現在會採用以下格式:
{ "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" } }
取得評分、評論數量和評論
如要擷取商家的平均星級評等、評分總數 (評論總數) 或顧客評論文字,請在 X-Goog-FieldMask 標頭中加入對應的欄位:
rating和userRatingCount:傳回地點的平均評分 (1.0到5.0) 和評論總數。要求這些欄位會觸發 Place Details Enterprise SKU。reviews和reviewSummary:傳回最多五個使用者提交的Review物件,以及 AI 生成的評論摘要。要求這些欄位會觸發 Place Details Enterprise + Atmosphere SKU。
如果應用程式只需要星級評等和評論總數,請要求 rating 和 userRatingCount,但不要求 reviews,這樣要求就會維持在 Place Details Enterprise SKU 級別:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,rating,userRatingCount" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
如要一併擷取最多五個使用者提交的 Review 物件,請將 reviews 新增至欄位遮罩 (按 Place Details Enterprise + Atmosphere SKU 級別計費):
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,rating,userRatingCount,reviews" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
回應包含評分、總評分數量和 reviews 陣列:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" }, "rating": 4.2, "userRatingCount": 2594, "reviews": [ { "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/reviews/...", "relativePublishTimeDescription": "a month ago", "rating": 5, "text": { "text": "Iconic tech campus with visitor areas and cafes.", "languageCode": "en" }, "authorAttribution": { "displayName": "Alex Rivera" } } ] }
取得地址描述元
地址描述元提供地點位置的相關資訊,包括附近地標和所在區域。
以下範例顯示 Place Details (新版) 要求,查詢聖荷西購物中心內的百貨公司。在本範例中,您在欄位遮罩中加入 addressDescriptors:
curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: name,displayName,addressDescriptor"
回應包含要求中指定的地點、附近地標清單和與該地點的距離,以及區域清單和與該地點的包含關係:
{ "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "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": 220.29175 }, { "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": 329.45178 }, { "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "displayName": { "text": "Monroe Parking Garage", "languageCode": "en" }, "types": [ "establishment", "parking", "point_of_interest" ], "straightLineDistanceMeters": 227.05153 }, { "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM", "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM", "displayName": { "text": "Studios Inn by Daiwa Living California Inc.", "languageCode": "en" }, "types": [ "establishment", "lodging", "point_of_interest", "real_estate_agency" ], "straightLineDistanceMeters": 299.9955 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 157.70943 } ], "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" } ] } }
取得已遷移地點的 Place Details
如果應用程式參照的地點已遷移,您可以使用 movedPlace 和 movedPlaceId 欄位,取得新地點的詳細資料。
如果地點永久停業,Place Details (新版) 會在 businessStatus 欄位中傳回 CLOSED_PERMANENTLY,並在回應主體中省略 movedPlace 和 movedPlaceId 欄位。
如果地點已搬遷到新位置,Place Details (新版) 會在 businessStatus 欄位中傳回 CLOSED_PERMANENTLY,並在回應主體的 movedPlace 和 movedPlaceId 欄位中傳回新位置。
如果地點未遷移,Place Details (新版) 不會在回應主體中傳回 movedPlace 或 movedPlaceId。
以下範例要求加拿大魁北克 Marche IGA St-Canut 的地點資訊:
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
這項要求會傳回下列回應:
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
如要要求新地點的詳細資料,請在新的 Place Details (新版) 要求中,於 movedPlace 欄位使用 Place 資源名稱。
如果地點多次搬遷,可能需要多次鏈結 Place Details (New) 要求,才能取得目前位置的詳細資料。地點結果的 movedPlace 和 movedPlaceId 欄位只會指向下一個位置,而非最後已知位置。如果 Place Details (新版) 要求省略回應主體中的 movedPlace 和 movedPlaceId 欄位,地點就會位於目前位置。
尋找日後營業的商家
您可以要求提供預計在未來開幕的商家詳細資料。
如果預計開幕日期至少包含月份,且距離現在不到 90 天,Nearby Search (新版) 就會填入 openingDate 欄位。
以下範例顯示 Nearby Search (新版) 要求,查詢愛達荷州新梅多斯即將開幕的商家:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
回應包含地點的營業狀態和預計開幕日期:
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
取得大眾運輸站資訊
您可以使用 Place Details (新版) 取得大眾運輸站點的資訊。回應主體包含車站資訊,包括車站名稱、所屬運輸公司,以及停靠該車站的大眾運輸路線。此外,回應還包含車輛圖示和顏色,可用於顯示大眾運輸站點資訊。
以下範例顯示中央車站的大眾運輸站點資訊要求:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
回應主體包含半徑範圍內各車站的資訊、車站服務的路線、運輸公司在該停靠站發布的快訊,以及出發資訊:
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
取得入口和導航點
您可以要求目的地的入口和導航點。入口定義了地點的出入口 (例如機場或購物中心的不同閘門)。導航點定義了導航應結束的路邊位置,有助於將使用者導向正確的道路一側或特定下車點。
導航點會傳回 navigationPointToken。您可以將這個權杖傳遞至 Navigation SDK (適用於 Android 或 iOS) 或 Routes API,引導司機前往特定位置。詳情請參閱「導航點權杖」。
以下範例要求舊金山國際機場 (地點 ID ChIJVVVVVYx3j4ARP-3NGldc8qQ) 的詳細資料,並在欄位遮罩中加入 entrances 和 navigationPoints:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,entrances,navigationPoints" \ https://places.googleapis.com/v1/places/ChIJVVVVVYx3j4ARP-3NGldc8qQ
回應包含地點的入口和導航點:
{ "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] }
試試看!
APIs Explorer 可讓您提出範例要求,熟悉 API 和 API 選項。
選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中,選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中,選取全螢幕圖示 fullscreen,展開 APIs Explorer 視窗。