Place Details (最新)

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

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

簡介

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

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

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

試試看！

Place Details (新版) 要求

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
  moved_place
  moved_place_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
  openingDate
  primaryType
  primaryTypeDisplayName
  pureServiceAreaBusiness
  subDestinations
  timeZone
  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 (新推出) 範例

以下範例會要求地點的詳細資料：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"
        }
      ]
    }
  }

取得搬遷地點的詳細資料

如果應用程式中參照的地點已搬遷，您可以使用 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 天，系統就會在「附近搜尋 (新版)」中填入「openingDate」欄位。

以下範例顯示在愛達荷州新梅多斯，對未來即將開幕的商家提出的 Nearby Search (New) 要求：

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
  }
}

試試看！

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

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

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

簡介

Place Details (新版) 要求

Place Details (新推出) 回應

必要參數

FieldMask

placeId

選用參數

languageCode

regionCode

sessionToken

Place Details (新推出) 範例

取得地址描述元

取得搬遷地點的詳細資料

尋找日後營業的商家

試試看！

Place Details (最新)