本頁面由 Cloud Translation API 翻譯而成。

Place Details (最新)

取得地點 ID 後，您可以提出 Place Details (新版) 要求，針對特定建築物或搜尋點要求更多詳細資料。Place Details (新) 要求會傳回有關指定地點的詳盡資訊，例如完整地址、電話號碼、使用者評分和評論。

取得地點 ID 的方法有很多種，例如：

您可以透過 API Explorer 發出即時要求，熟悉 API 和 API 選項：

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 物件做為回應。請在回應中執行下列操作：

回應會以 Place 物件表示。Place 物件包含地點的詳細資訊。
要求中傳遞的 FieldMask 會指定 Place 物件中傳回的欄位清單。

完整的 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: *
```
萬用字元「*」會選取所有欄位。不過，雖然萬用字元可在開發過程中使用，但 Google 我們不建議在實際工作環境中使用萬用字元 (*) 回應欄位遮罩，因為可傳回大量資料。
如需使用 iconMaskBaseUri 和 iconBackgroundColor 的進一步指引，請參閱「地點圖示」一節。
請指定下列一或多個欄位：
- 下列欄位會觸發 Place Details (僅限 ID) SKU：
  
  id、name^*、photos
  
  ^* name 欄位包含地點資源名稱，格式為：places/PLACE_ID。使用 displayName 存取地點的文字名稱。
- 下列欄位會觸發 Place Details (Location Only) SKU：
  
  addressComponents、 adrFormatAddress、 formattedAddress、 location、 plusCode、 shortFormattedAddress、 types、 viewport
- 下列欄位會觸發 Place Details (Basic) SKU：
  
  accessibilityOptions、businessStatus、displayName、googleMapsUri、iconBackgroundColor、iconMaskBaseUri、primaryType、primaryTypeDisplayName、subDestinations、utcOffsetMinutes
- 下列欄位會觸發 Place Details (Advanced) 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、 /servesBeerservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout
placeId

可識別特定地點的文字 ID，從文字搜尋 (New) 或 Nearby Search (New) 傳回。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。

places/PLACE_ID 字串也稱為地點資源名稱。在 Place Details (新功能)、Nearby Search (New) 和 Text Search (New) 要求的回應中，這個字串會納入回應的 name 欄位中。獨立地點 ID 包含在回應的 id 欄位中。

注意： 在現有的 Place Details 中，回應的 name 欄位含有地點的人類可讀名稱。在新的 API 中，這個欄位已改名為 displayName。

自選參數

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 (新版) 會使用工作階段符記，將使用者自動完成搜尋中的查詢和地點選取階段歸入不同的工作階段，以便計費。工作階段符記會傳遞至 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
```
視需要展開「顯示標準參數」，並將 fields 參數設為欄位遮罩。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出要求的帳戶。
在 API Explorer 面板中選取展開圖示，展開 API Explorer 視窗。

Place Details (最新)

Place Details (新) 要求

Place Details (新版) 回應

必要參數

FieldMask

placeId

自選參數

languageCode

regionCode

sessionToken

Place Details 範例

試試看！