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

Place Details (最新)

選取平台： Android iOS JavaScript 網頁服務

取得地點 ID後，您可以發出 Place Details (New) 要求，取得特定設施或興趣點的更多詳細資料。Place Details (New) 要求會傳回指定地點的更完整資訊，例如完整地址、電話號碼、使用者評分和評論。

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

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

Place Details (New) 要求

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 Essentials IDs Only SKU：
  
  attributions
  id
  name^*
  photos
  
  ^* name 欄位包含以下格式的資源名稱：places/PLACE_ID。如要取得地點的文字名稱，請在 Pro SKU 中要求 displayName 欄位。
- 下列欄位會觸發 Place Details Essentials SKU：
  
  addressComponents
  addressDescriptor^*
  adrFormatAddress
  formattedAddress
  location
  plusCode
  postalAddress
  shortFormattedAddress
  types
  viewport
  
  ^* 地址描述符通常適用於印度的客戶，其他地區則為實驗功能。
- 下列欄位會觸發 Place Details Pro SKU：
  
  accessibilityOptions
  businessStatus
  containingPlaces
  displayName
  googleMapsLinks^*
  googleMapsUri
  iconBackgroundColor
  iconMaskBaseUri
  primaryType
  primaryTypeDisplayName
  pureServiceAreaBusiness
  subDestinations
  utcOffsetMinutes
  
  ^* googleMapsLinks 欄位目前處於 GA 預先發布階段，因此在預先發布版期間使用時不會產生任何費用，也就是帳單金額為 $0 美元。
- 下列欄位會觸發 Place Details Enterprise SKU：
  
  currentOpeningHours
  currentSecondaryOpeningHours
  internationalPhoneNumber
  nationalPhoneNumber
  priceLevel
  priceRange
  rating
  regularOpeningHours
  regularSecondaryOpeningHours
  userRatingCount
  websiteUri
- 下列欄位會觸發 Place Details Enterprise + Atmosphere SKU：
  
  allowsDogs
  curbsidePickup
  delivery
  dineIn
  editorialSummary
  evChargeOptions
  fuelOptions
  goodForChildren
  goodForGroups
  goodForWatchingSports
  liveMusic
  menuForChildren
  parkingOptions
  paymentOptions
  outdoorSeating
  reservable
  restroom
  reviews
  routingSummaries^*
  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 欄位中。

注意： 在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 (New) 會使用工作階段符記，將使用者自動完成搜尋的查詢和地點選取階段歸入不同的工作階段，以用於計費。系統會將工作階段符記傳遞至 Autocomplete (新版) 呼叫後的 Place Details (新版) 呼叫。詳情請參閱「工作階段符記」。

Place Details (New) 範例

基本要求

以下範例會透過 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"
  }
}

取得地址描述元

地址描述符會提供地點位置的關聯資訊，包括附近地標和包含區域。

注意：地址描述符已全面開放給印度的客戶使用，其他地區則為實驗功能。如果 Places API 要求在欄位遮罩中只使用 addressDescriptor，系統會以 SKU：Places API Place Details Essentials 計費。

以下範例顯示聖荷西購物中心內百貨公司的 Place Details (New) 要求。在本範例中，您會在欄位遮罩中加入 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"
        }
      ]
    }
  }

試試看！

您可以使用 APIs Explorer 建立範例要求，熟悉 API 和 API 選項。

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「執行」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在「API Explorer」面板中，選取全螢幕圖示 fullscreen 即可展開「API Explorer」視窗。

Place Details (最新)

Place Details (New) 要求

Place Details (新版) 回應

必要參數

FieldMask

placeId

選用參數

languageCode

regionCode

sessionToken

Place Details (New) 範例

基本要求

取得地址描述元

試試看！