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

Place Details (最新)

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

歐洲經濟區 (EEA) 開發人員

簡介

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

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

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

試試看！

Place Details (New) 要求

Place Details (New) 要求是 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 (New) 會傳回 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
- 下列欄位會觸發 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
  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
  
  ^* 僅限文字搜尋和附近搜尋
placeId

用來識別特定地點的文字 ID，由 Text Search (新版) 或 Nearby Search (新版) 傳回。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。

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

注意： 在地點詳細資料 (舊版) 中，回應的 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 (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。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 展開 APIs Explorer 視窗。

Place Details (最新) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

Place Details (New) 要求

Place Details (新版) 回應

必要參數

FieldMask

placeId

選用參數

languageCode

regionCode

sessionToken

Place Details (New) 示例

取得地址描述元

試試看！

Place Details (最新)