取得地點 ID 後,即可 要求取得特定建築物的詳細資訊,或 透過啟動 Place Details (新功能) 請求。Place Details (新) 要求會傳回關於地點的詳盡資訊 例如完整地址、電話號碼、使用者評分和評論
取得地點 ID 的方法有很多種,例如:
- Text Search (新版) 或 Nearby Search (新版)
- Geocoding API
- Routes API
- Address Validation API
- Place Autocomplete
API Explorer 可讓您發出即時要求,以便熟悉 API 以及 API 選項:
試試看!Place Details (新) 要求
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 物件。在回覆中:
完整的 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 (僅限 ID) 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 (基本) SKU:
accessibilityOptions
,businessStatus
,displayName
,googleMapsUri
,iconBackgroundColor
,iconMaskBaseUri
,primaryType
,primaryTypeDisplayName
,subDestinations
,utcOffsetMinutes
下列欄位會觸發 Place Details (進階) 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
,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 會使用 最接近的相符項目。
- 偏好的語言對於 Google 提供的 API 選擇傳回的 物件,以及傳回的順序。 地理編碼器會根據語言,以不同方式解讀縮寫 例如街道類型的縮寫 且在某種語言中有效,但是沒有另一種語言。
regionCode
用於設定回應格式的區碼,以 也就是雙字元 CLDR 代碼值。沒有預設值。
如果回應中
formattedAddress
欄位的國家/地區名稱與regionCode
,formattedAddress
中省略了國家/地區代碼。 這個參數不會影響adrFormatAddress
,一律包含國家/地區 名稱或shortFormattedAddress
上 (絕不會包含此項目)。大部分 CLDR 代碼與 ISO 3166-1 代碼相同 有一些值得注意的例外情況舉例來說,英國的 ccTLD 是 「uk」(.co.uk),但 ISO 3166-1 代碼卻是「gb」(技術上來說 「大不列顛暨北愛爾蘭聯合王國」)。 這個參數會根據適用法律影響結果。
-
sessionToken
工作階段符記是使用者產生的字串,可追蹤自動完成功能 (新) 呼叫做為「工作階段」。自動完成 (新版) 會使用工作階段符記 將使用者自動完成搜尋的查詢和地點選擇階段歸入不同的工作階段 做為帳單用途工作階段符記會傳送至 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 選項
如何提出要求:
- 選取 API 圖示
。 網頁右側。
- 視需要將
name
參數設為:places/PLACE_ID
- 視需要展開「顯示標準參數」並進行設定
fields
參數 欄位遮罩。 - 選取「執行」按鈕。在彈出式視窗中,選擇要使用的帳戶 發出要求
在 API Explorer 面板中,選取展開圖示
,展開「API Explorer」視窗。