取得地點 ID 後,您就可以提出 Place Details (新版) 要求,要求取得特定建築物或搜尋點的詳細資料。Place Details (新版) 要求會傳回有關地點的詳盡資訊,例如完整地址、電話號碼、使用者評分和評論。
取得地點 ID 的方法有很多種,例如:
- Text Search (新版) 或 Nearby Search (新版)
- Geocoding API
- Routes API
- Address Validation API
- Place Autocomplete
API 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 (僅限 ID) SKU:
attributions
、id
、name
*、photos
*name
欄位包含以下格式的地點資源名稱:places/PLACE_ID
。
使用displayName
即可存取地點的文字名稱。下列欄位會觸發 Place Details (Location Only) SKU:
addressComponents
、adrFormatAddress
、formattedAddress
、location
、plusCode
、shortFormattedAddress
、types
、viewport
下列欄位會觸發 Place Details (基本) SKU:
accessibilityOptions
、businessStatus
、displayName
、googleMapsUri
、iconBackgroundColor
、iconMaskBaseUri
、primaryType
、primaryTypeDisplayName
、subDestinations
、utcOffsetMinutes
下列欄位會觸發 Place Details (進階) SKU:
currentOpeningHours
、currentSecondaryOpeningHours
、internationalPhoneNumber
、nationalPhoneNumber
、priceLevel
、rating
、regularOpeningHours
、regularSecondaryOpeningHours
、userRatingCount
、websiteUri
下列欄位會觸發 Place Details (Preferred) SKU:
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
可識別特定地點的文字 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 (新) 呼叫視為「工作階段」來追蹤。Autocomplete (新版) 會使用工作階段符記,將使用者自動完成搜尋的查詢查詢及地點選取階段歸入不同的工作階段,以用於計費。工作階段符記會傳遞至 Place Details (新版) 呼叫後方,此呼叫會追蹤 Autocomplete (新版) 呼叫。詳情請參閱工作階段符記。
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" } }
試試看!
API Explorer 可讓您提出要求範例,以便熟悉 API 和 API 選項。
如何提出要求:
- 選取頁面右側的 API 圖示 。
- 視需要將
name
參數設為:places/PLACE_ID
- 視需要展開「Show Standard parameters」,然後將
fields
參數設為欄位遮罩。 - 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出要求的帳戶。
在「API Explorer」面板中選取展開圖示 ,展開「API Explorer」視窗。