Places Service

PlacesService 類別

google.maps.places.PlacesService 類別

包含搜尋地點及擷取地點詳細資料的方法。

呼叫 const {PlacesService} = await google.maps.importLibrary("places") 即可存取。請參閱 Maps JavaScript API 中的程式庫。
PlacesService
PlacesService(attrContainer)
參數： 
建立 PlacesService 的新例項，以在特定容器中顯示屬性。
findPlaceFromPhoneNumber
findPlaceFromPhoneNumber(request, callback)
參數： 
傳回值：無
根據電話號碼擷取地點清單。在大部分情況下，結果清單中只會有一個項目，但如果要求是模糊不清的結果，系統可能會傳回多件結果。傳遞至回呼的 PlaceResult 是完整 PlaceResult 的子集。應用程式只要呼叫 PlacesService.getDetails 並傳遞所需位置的 PlaceResult.place_id，就能取得每個地點的詳細 PlaceResult。
findPlaceFromQuery
findPlaceFromQuery(request, callback)
參數： 
傳回值：無
根據查詢字串擷取地點清單。在大部分情況下，結果清單中只會有一個項目，但如果要求是模糊不清的結果，系統可能會傳回多件結果。傳遞至回呼的 PlaceResult 是完整 PlaceResult 的子集。應用程式只要呼叫 PlacesService.getDetails 並傳遞所需位置的 PlaceResult.place_id，就能取得每個地點的詳細 PlaceResult。
getDetails
getDetails(request, callback)
參數： 
傳回值：無
擷取指定 placeId 所識別地點的詳細資料。
nearbySearch
nearbySearch(request, callback)
參數： 
傳回值：無
根據關鍵字或類型，擷取特定位置附近的地點清單。您必須透過傳遞 LatLngBounds 或 location 和 radius 參數來指定位置。傳遞至回呼的 PlaceResult 是完整 PlaceResult 的子集。只要傳送 Place Details 要求，傳遞所需地點的 PlaceResult.place_id，應用程式就能取得每個地點的詳細 PlaceResult。PlaceSearchPagination 物件可用於擷取其他結果頁面 (如果這是最後一頁，或只有一頁結果，則為空值)。
textSearch
textSearch(request, callback)
參數： 
傳回值：無
根據查詢字串 (例如「臺北披薩」或「渥太華附近的鞋店」) 擷取地點清單。位置參數為選用項目；指定位置時，結果只會偏向附近的結果，不會限制顯示區域內的地點。當您想使用任意字串搜尋地點，且不想將搜尋結果限制在特定位置時，請使用 textSearch。PlaceSearchPagination 物件可用於擷取其他結果頁面 (如果這是最後一頁，或只有一頁結果，則為空值)。

PlaceDetailsRequest 介面

google.maps.places.PlaceDetailsRequest 介面

要傳送到 PlacesService 的地點詳細資料查詢。
placeId
類型：  string
要求詳細資料的地點 ID。
fields optional
類型：  Array<string> optional
詳細資料回應中要納入的欄位，會產生費用。如未指定任何欄位，或已傳入 ['ALL']，系統會傳回所有可用的欄位並產生費用 (不建議用於實際工作環境部署作業)。如需欄位清單，請參閱 PlaceResult。巢狀欄位可使用點路徑指定 (例如 "geometry.location")。
language optional
類型：  string optional
應傳回詳細資料的語言語言 ID。請參閱支援語言清單。
region optional
類型：  string optional
使用者所在區域的區碼。這可能會影響系統能夠傳回哪些相片，也可能影響其他因素。區碼接受 ccTLD (「頂層網域」) 的兩位字元值多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，但 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。
sessionToken optional
類型：  AutocompleteSessionToken optional
用於將詳細資料要求與自動完成工作階段結合的專屬參考資料。

FindPlaceFromPhoneNumberRequest 介面

google.maps.places.FindPlaceFromPhoneNumberRequest 介面

要傳送至 PlacesService.findPlaceFromPhoneNumber 的文字搜尋要求中的地點。
fields
類型：  Array<string>
要納入回應的欄位，也會收費。如果傳入 ['ALL']，系統會傳回所有可用的欄位並產生費用 (不建議用於實際工作環境部署作業)。如需欄位清單，請參閱 PlaceResult。巢狀欄位可使用點路徑指定 (例如 "geometry.location")。
phoneNumber
類型：  string
要查詢地點的電話號碼。格式須為 E.164。
language optional
類型：  string optional
應以哪種語言傳回姓名和地址的語言 ID (如果可能的話)。請參閱支援語言清單。
locationBias optional
類型：  LocationBias optional
搜尋地點時使用的偏誤。結果可能會偏誤 (但不限於) 指定的 LocationBias。

FindPlaceFromQueryRequest 介面

google.maps.places.FindPlaceFromQueryRequest 介面

要傳送至 PlacesService.findPlaceFromQuery 的文字搜尋要求中的地點。
fields
類型：  Array<string>
要納入回應的欄位，也會收費。如果傳入 ['ALL']，系統會傳回所有可用的欄位並產生費用 (不建議用於實際工作環境部署作業)。如需欄位清單，請參閱 PlaceResult。巢狀欄位可使用點路徑指定 (例如 "geometry.location")。
query
類型：  string
要求的查詢。例如地點的名稱或地址。
language optional
類型：  string optional
應以哪種語言傳回姓名和地址的語言 ID (如果可能的話)。請參閱支援語言清單。
locationBias optional
類型：  LocationBias optional
搜尋地點時使用的偏誤。結果可能會偏誤 (但不限於) 指定的 LocationBias。

PlaceSearchRequest 介面

google.maps.places.PlaceSearchRequest 介面

要傳送到 PlacesService 的地點搜尋查詢。
bounds optional
類型：  LatLngBounds|LatLngBoundsLiteral optional
用於搜尋地點的邊界。如果設定 bounds，系統會忽略 location 和 radius。
keyword optional
類型：  string optional
要與所有可用欄位比對的字詞，包括但不限於名稱、類型、地址、客戶評論以及其他第三方內容。
language optional
類型：  string optional
應以哪種語言傳回姓名和地址的語言 ID (如果可能的話)。請參閱支援語言清單。
location optional
類型：  LatLng|LatLngLiteral optional
用於搜尋附近地點的位置。
maxPriceLevel optional
類型：  number optional
限制系統只傳回指定價格等級或更低的地點。有效值介於 0 (最便宜) 和 4 (最昂貴)，含首尾。必須大於或等於 minPrice (如有指定)。
minPriceLevel optional
類型：  number optional
限制系統只傳回指定價格等級以上的地點。有效值介於 0 (最便宜) 和 4 (最昂貴)，含首尾。必須小於或等於 maxPrice (如有指定)。
name optional
類型：  string optional
等同於 keyword。這個欄位的值會與 keyword 欄位的值合併，並做為同一個搜尋字串的一部分傳送。
openNow optional
類型：  boolean optional
只搜尋目前營業中的地點。
radius optional
類型：  number optional
指定地點與搜尋「地點」的距離 (以公尺為單位)。允許的最大值為 50 000。
rankBy optional
類型：  RankBy optional
指定傳回結果時使用的排序方法。請注意，當 rankBy 設為 DISTANCE 時，您必須指定 location，但無法指定 radius 或 bounds。
type optional
類型：  string optional
搜尋指定類型的地點。類型會轉譯為要求目標地區的當地語言，並做為查詢字串使用。如果同時提供查詢，該查詢會串連為本地化的類型字串。回應中會捨棄其他類型的結果。這個欄位可用於執行不同語言及地區獨立的類別搜尋。有效的類型請參閱這裡。

TextSearchRequest 介面

google.maps.places.TextSearchRequest 介面

要傳送到 PlacesService 的文字搜尋要求。
bounds optional
類型：  LatLngBounds|LatLngBoundsLiteral optional
用來在搜尋地點時自訂調整結果的邊界 (選用)。如果設定 bounds，系統會忽略 location 和 radius。結果不會僅限於這些邊界內的結果，但內部結果的排名會較高。
language optional
類型：  string optional
應以哪種語言傳回姓名和地址的語言 ID (如果可能的話)。請參閱支援語言清單。
location optional
類型：  LatLng|LatLngLiteral optional
搜尋「地點」時，用於自訂調整結果的區域中心。
query optional
類型：  string optional
要求的查詢字詞。例如地點名稱 (例如「艾菲爾鐵塔」)，後面加上地點名稱 (例如「臺北市披薩」)，或是地點名稱，後面加上地點歧義 (例如「雪梨的 Starbucks」)。
radius optional
類型：  number optional
搜尋「地點」時，用於調整結果的區域半徑 (以公尺為單位)。
region optional
類型：  string optional
針對特定結果進行自訂調整的區碼。區碼接受 ccTLD (「頂層網域」) 的兩位字元值多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，但 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。
type optional
類型：  string optional
搜尋指定類型的地點。類型會轉譯為要求目標地區的當地語言，並做為查詢字串使用。如果同時提供查詢，該查詢會串連為本地化的類型字串。回應中會捨棄其他類型的結果。這個欄位可用於執行不同語言及地區獨立的類別搜尋。有效的類型請參閱這裡。

RankBy 常數

google.maps.places.RankBy 常數

PlaceSearchRequest 的排名選項。

呼叫 const {RankBy} = await google.maps.importLibrary("places") 即可存取。請參閱 Maps JavaScript API 中的程式庫。
DISTANCE 依與地點的距離排名地點結果。
PROMINENCE 依顯眼程度排名地點結果。

LocationBias typedef

google.maps.places.LocationBias typedef

LocationBias 代表搜尋「地點」時要使用的軟邊界或提示。結果可能來自指定區域以外的內容。如要使用目前使用者的 IP 位址做為自訂調整，您可以指定 "IP_BIAS" 字串。注意：如果您使用 Circle，則必須定義中心點和半徑。

LatLng|LatLngLiteral|LatLngBounds|LatLngBoundsLiteral|Circle|CircleLiteral|string

LocationRestriction typedef

google.maps.places.LocationRestriction typedef

LocationRestriction 是搜尋地點時要使用的嚴格邊界。

LatLngBounds|LatLngBoundsLiteral

PlacesServiceStatus 常數

google.maps.places.PlacesServiceStatus 常數

PlacesService 在搜尋完成時傳回的狀態。您可以採用值或常數名稱來指定這些參數。例如 'OK' 或 google.maps.places.PlacesServiceStatus.OK。

呼叫 const {PlacesServiceStatus} = await google.maps.importLibrary("places") 即可存取。請參閱 Maps JavaScript API 中的程式庫。
INVALID_REQUEST 這個要求無效。
NOT_FOUND 找不到參照的地點。
OK 回應包含有效的結果。
OVER_QUERY_LIMIT 應用程式超出要求配額。
REQUEST_DENIED 不允許應用程式使用 PlacesService。
UNKNOWN_ERROR 伺服器發生錯誤，無法處理 PlacesService 要求。如果您再試一次，可能會成功進行要求。
ZERO_RESULTS 找不到這項要求的結果。

PlaceSearchPagination 介面

google.maps.places.PlaceSearchPagination 介面

這個物件是用來擷取地點介面集結果的其他頁面。
hasNextPage
類型：  boolean
指出是否有其他結果。有其他結果網頁時，值為 true。
nextPage
nextPage()
參數：無
傳回值：無
擷取下一頁的結果。使用一開始提供給第一個搜尋要求的回呼函式。

PlaceResult 介面

google.maps.places.PlaceResult 介面

定義地點相關資訊。
address_components optional
類型：  Array<GeocoderAddressComponent> optional
此地點位置的地址元件集合。僅適用於 PlacesService.getDetails。
adr_address optional
類型：  string optional
以 adr 微格式表示地點的地址。僅適用於 PlacesService.getDetails。
aspects optional
類型：  Array<PlaceAspectRating> optional
此地點的評分依據，是根據 Google 和 Zagat 使用者的評論計算而得。評分範圍為 0 到 30 分。
business_status optional
類型：  BusinessStatus optional
此標記用來表示地點的營業狀態，如果商家是商家 (表示該地點仍在營運，或暫時或永久停業)。如果沒有可用資料，則搜尋結果或詳細資料回應中不會顯示旗標。
formatted_address optional
類型：  string optional
地點的完整地址。
formatted_phone_number optional
類型：  string optional
地點的電話號碼，格式取決於 號碼的地方慣例。僅適用於 PlacesService.getDetails。
geometry optional
類型：  PlaceGeometry optional
地點的幾何圖形相關資訊。
html_attributions optional
類型：  Array<string> optional
此地點結果所要顯示的作者資訊文字。無論要求 fields 為何，系統一律會傳回可用的 html_attributions，而必須顯示這些 html_attributions。
icon optional
類型：  string optional
可用來代表此地點類別的圖片資源網址。
icon_background_color optional
類型：  string optional
與地點圖示搭配使用的背景顏色。另請參閱 PlaceResult.icon_mask_base_uri。
icon_mask_base_uri optional
類型：  string optional
圖示遮罩的截斷網址。在結尾附加副檔名 (例如 .svg 或 .png) 以存取不同的圖示類型。
international_phone_number optional
類型：  string optional
地點的電話號碼 (國際格式)。國際通用格式包含國碼，而且前置字元為加號 (+)。僅適用於 PlacesService.getDetails。
name optional
類型：  string optional
地點的名稱。注意：在使用者輸入的「地點」中，這是指使用者輸入的原始文字。因此，使用這項資料時請格外小心，因為惡意使用者可能會試圖利用這項資料發動程式碼插入攻擊 (請參閱 http://en.wikipedia.org/wiki/Code_injection)。
opening_hours optional
類型：  PlaceOpeningHours optional
定義地點的開始或關閉時間。
permanently_closed optional
類型：  boolean optional
指出地點是否永久關閉的標記。如果地點運作正常，或是沒有任何資料，回應中就不會顯示該標記。
photos optional
類型：  Array<PlacePhoto> optional
此地點的相片。集合最多包含 10 個 PlacePhoto 物件。
place_id optional
類型：  string optional
地點的專屬 ID。
plus_code optional
類型：  PlacePlusCode optional
定義地點的開放區碼或「plus code」。
price_level optional
類型：  number optional
地點的價格等級，由 0 到 4 表示。價格等級的計算方式如下：
  • 0：免費
  • 1：低價位
  • 2：中
  • 3：高價位
  • 4：超高價位
rating optional
類型：  number optional
評分：1.0 到 5.0，依使用者對此地點的使用者評論計算。
reviews optional
類型：  Array<PlaceReview> optional
這個地點的評論清單。僅適用於 PlacesService.getDetails。
types optional
類型：  Array<string> optional
此地點的陣列類型 (例如 ["political", "locality"] 或 ["restaurant", "establishment"])。
url optional
類型：  string optional
這個地點的 Google 官方頁面網址。這是 Google 擁有的頁面，內含有關「地點」的實用資訊。僅適用於 PlacesService.getDetails。
user_ratings_total optional
類型：  number optional
對此地點的「PlaceResult.rating」貢獻的使用者評分次數。
utc_offset optional
類型：  number optional
與地點目前時區的世界標準時間相差值 (以分鐘為單位)。舉例來說，澳洲雪梨在日光節約時間比世界標準時間提前 11 小時，因此 utc_offset 會是 660。如果時區晚於世界標準時間 (UTC)，偏移量就會是負數。例如，utc_offset 是維德角的 -60。僅適用於 PlacesService.getDetails。
utc_offset_minutes optional
類型：  number optional
與地點目前時區的世界標準時間相差值 (以分鐘為單位)。舉例來說，澳洲雪梨在日光節約時間比世界標準時間提前 11 小時，因此 utc_offset_minutes 會是 660。如果時區晚於世界標準時間 (UTC)，偏移量就會是負數。例如，utc_offset_minutes 是維德角的 -60。僅適用於 PlacesService.getDetails。
vicinity optional
類型：  string optional
地點的簡化地址，包括街道名稱、門牌號碼和縣市，但不含省/州、郵遞區號或國家/地區。舉例來說，Google 澳洲雪梨辦公室的 vicinity 值為 "48 Pirrama Road, Pyrmont"。僅適用於 PlacesService.getDetails。
website optional
類型：  string optional
這個地點的官方網站，例如商家的首頁。僅適用於 PlacesService.getDetails。

PlaceAspectRating 介面

google.maps.places.PlaceAspectRating 介面

定義使用者評論過的地點相關資訊。
rating
類型：  number
此面向的評分。如果是個別評論，這個值是 0 到 3 之間的整數。針對地點的匯總評分，這個值是 0 到 30 之間的整數。
type
類型：  string
切面類型。例如 "food"、"decor"、"service" 或 "overall"。

BusinessStatus 常數

google.maps.places.BusinessStatus 常數

Place 的營業狀態 (如果商家為商家)，則會在 PlaceResult 中傳回 (表示該地點目前營業中，或暫時或永久停業)。請以值或常數名稱指定這些項目 (例如：'OPERATIONAL' 或 google.maps.places.BusinessStatus.OPERATIONAL)。

呼叫 const {BusinessStatus} = await google.maps.importLibrary("places") 即可存取。請參閱 Maps JavaScript API 中的程式庫。
CLOSED_PERMANENTLY 商家已永久停業。
CLOSED_TEMPORARILY 商家暫停營業。
OPERATIONAL 商家照常營運。

PlaceGeometry 介面

google.maps.places.PlaceGeometry 介面

定義地點的幾何圖形相關資訊。
location optional
類型：  LatLng optional
地點的位置。
viewport optional
類型：  LatLngBounds optional
在地圖上顯示這個地點時偏好的可視區域。如果無法取得地點偏好的可視區域，此屬性將為 null。僅適用於 PlacesService.getDetails。

PlaceOpeningHours 介面

google.maps.places.PlaceOpeningHours 介面

定義地點的營業時間相關資訊。
open_now optional
類型：  boolean optional
地點目前是否營業中。
periods optional
類型：  Array<PlaceOpeningHoursPeriod> optional
一週中每天的開幕期，從週日開始，按時間順序排列。不開放該地點的營業日。僅適用於 PlacesService.getDetails。
weekday_text optional
類型：  Array<string> optional
包含七個字串的陣列，以特定格式表示一週內每天的營業時間。「地點介面集服務」會根據目前語言調整營業時間格式和本地化內容。此陣列中的元素順序視語言而定。有些語言是以週一做為每週起始日，有些則是週日。僅適用於 PlacesService.getDetails。其他呼叫可能會傳回空的陣列。
isOpen
isOpen([date])
參數： 
  • date：Date optional
傳回值：  boolean|undefined
查看地點是否營業中 (未註明日期時)，或是否在指定日期營業。如果這個地點沒有 PlaceResult.utc_offset_minutes 或 PlaceOpeningHours.periods，則會傳回 undefined (PlaceOpeningHours.periods 只能透過 PlacesService.getDetails)。這個方法不會考慮特殊營業時間，例如假日營業時間。

PlaceOpeningHoursPeriod 介面

google.maps.places.PlaceOpeningHoursPeriod 介面

定義地點營業時間的結構化資訊。注意：如果地點全年無休，回應中會缺少 close 部分。用戶端可以將「持續開啟」表示為 open 時段，其中包含 day (值為 0，time) 的值 ("0000") (不含 close)。
open
地點的開始時間。
close optional
類型：  PlaceOpeningHoursTime optional
地點的打烊時間。

PlaceOpeningHoursTime 介面

google.maps.places.PlaceOpeningHoursTime 介面

定義地點的開始或關閉時間。
day
類型：  number
星期幾，以 [0, 6] 範圍內的數字，從週日開始。例如，2 表示週二。
hours
類型：  number
PlaceOpeningHoursTime.time 以數字表示的小時數，介於 [0, 23] 範圍內。系統將以地點的時區為準。
minutes
類型：  number
PlaceOpeningHoursTime.time 以數字表示的分鐘 (介於 [0, 59] 範圍內)。系統會在地點所在的時區顯示這項資訊。
time
類型：  string
以 24 小時「hhmm」格式表示的時間。值的範圍是 ["0000", "2359"]。系統記錄的時間會以地點的時區為準。
nextDate optional
類型：  number optional
表示此 PlaceOpeningHoursTime 下次出現時間的時間戳記 (以 Epoch 紀元時間起算的毫秒為單位，適合與 new Date() 搭配使用)。這個值是根據當週 PlaceOpeningHoursTime.day、PlaceOpeningHoursTime.time 和 PlaceResult.utc_offset_minutes 計算而得。如果 PlaceResult.utc_offset_minutes 為 undefined，則 nextDate 會是 undefined。

PlacePlusCode 介面

google.maps.places.PlacePlusCode 介面

定義地點的開放區碼或「Plus Codes」。對於沒有詳細地址的地點，Plus Codes 可用於取代街道地址，例如無編號的建築物或無名街道。
global_code
類型：  string
以度數 1/8000 度為 1/8000 度的 plus code。例如 "8FVC9G8F+5W"。
compound_code optional
類型：  string optional
以度數 1/8000 的度數乘以 1/8000 度數的 plus code，其中第一個字元 (區碼) 會被捨棄，並替換成縣市說明。例如："9G8F+5W Zurich, Switzerland"。如果沒有可縮短代碼的適當縣市，則會省略這個欄位。

PlacePhoto 介面

google.maps.places.PlacePhoto 介面

代表地點的相片元素。
height
類型：  number
相片的高度 (以像素為單位)。
html_attributions
類型：  Array<string>
這張相片所要顯示的作者資訊文字。
width
類型：  number
相片的寬度 (以像素為單位)。
getUrl
getUrl([opts])
參數： 
傳回值：  string
傳回與指定選項相對應的圖片網址。

PhotoOptions 介面

google.maps.places.PhotoOptions 介面

定義相片要求選項。
maxHeight optional
類型：  number optional
傳回圖片的高度上限 (以像素為單位)。
maxWidth optional
類型：  number optional
傳回圖片的寬度上限 (以像素為單位)。

PlaceReview 介面

google.maps.places.PlaceReview 介面

代表某地點的一則評論。
author_name
類型：  string
評論者的名稱。
language
類型：  string
IETF 語言代碼，指出評論撰寫時使用的語言。請注意，這段程式碼只包含主要語言標記，不含表示國家/地區或區域的次要標記。舉例來說，所有英文評論都會標示為 'en'，而非「en-AU」或「en-UK」。
profile_photo_url
類型：  string
要求者個人資料圖片的網址。
relative_time_description
類型：  string
最近時間格式化的字串，以適合語言和國家/地區的形式，表示與目前時間相關的審查時間。例如 "a month ago"。
text
類型：  string
評論的文字。
time
類型：  number
審查時間戳記，以 Epoch 紀元時間起算的秒數表示。
aspects optional
類型：  Array<PlaceAspectRating> optional
評論評分的面向。評分範圍從 0 到 3。
author_url optional
類型：  string optional
評論者的個人資料網址。如果沒有評論者的個人資料，這個項目就會是 undefined。
rating optional
類型：  number optional
這則評論的評分，介於 1.0 到 5.0 (含) 之間。