Place Details (最新)

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

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

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

您可以透過 API 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: *

    指定下列一或多個欄位：

    • 下列欄位會觸發 Place Details (IDs Only) 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 (Basic) SKU：

      accessibilityOptions、businessStatus、containingPlaces、displayName、googleMapsLinks*、googleMapsUri、iconBackgroundColor、iconMaskBaseUri、primaryType、primaryTypeDisplayName、pureServiceAreaBusiness、subDestinations、utcOffsetMinutes

      *googleMapsLinks 欄位處於 GA 前測階段，在測試期間使用時不會產生任何費用，也就是帳單金額為 $0 美元。

    • 下列欄位會觸發 Place Details (Advanced) SKU：

      currentOpeningHours、currentSecondaryOpeningHours、internationalPhoneNumber、nationalPhoneNumber、priceLevel、priceRange、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、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 欄位中。

選用參數

  • 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 範例

以下範例會透過 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 選項。

提出要求的方法如下：

  1. 選取頁面右側的 API 圖示 展開 API Explorer。。
  2. 您可以選擇將 name 參數設為：
    places/PLACE_ID
  3. 您可以選擇展開「Show standard parameters」，然後將 fields 參數設為欄位遮罩。
  4. 選取「執行」按鈕。在彈出式視窗中，選擇要用來提出要求的帳戶。

  5. 在 API Explorer 面板中，選取展開圖示 展開 API Explorer。，展開 API Explorer 視窗。