Places Service

PlacesService class

google.maps.places.PlacesService class

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

撥打 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 的 Place Details 查詢。
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.PROMINENCE
指定傳回結果時使用的排名方法。請注意，當 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
要求的查詢字詞。例如地點名稱 (「巴黎鐵塔」)、類別加上地點名稱 (「紐約的披薩店」)，或地點名稱加上地點消歧資訊 (「雪梨的星巴克」)。
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()
參數：無
傳回值：  void
擷取下一頁的結果。使用提供給第一個搜尋要求的相同回呼函式。

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，且必須顯示。
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
這個地點的相片。集合最多會包含十個 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_offset 為 -60。僅適用於 PlacesService.getDetails。
utc_offset_minutes optional
類型：  number optional
地點目前時區與世界標準時間的時差 (以分鐘為單位)。舉例來說，澳洲雪梨在日光節約時間期間比世界標準時間快 11 小時，因此 utc_offset_minutes 為 660。如果時區比世界標準時間晚，偏移量為負值。舉例來說，維德角的 utc_offset_minutes 為 -60。僅適用於 PlacesService.getDetails。
vicinity optional
類型：  string optional
地點的簡化地址，包括街道名稱、門牌號碼和縣市，但不含省/州、郵遞區號或國家/地區。舉例來說，Google 澳洲雪梨辦公室的附近值為 "48 Pirrama Road, Pyrmont"。僅適用於 PlacesService.getDetails。
website optional
類型：  string optional
這個地點的官方網站，例如商家的首頁。僅適用於 PlacesService.getDetails。

PlaceAspectRating interface

google.maps.places.PlaceAspectRating 介面

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

BusinessStatus 常數

google.maps.places.BusinessStatus 常數

地點的營業狀態 (如果地點為商家)，會以 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 interface

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
時間戳記 (以 Epoch 紀元時間起算的毫秒數表示，適用於 new Date())，代表這個 PlaceOpeningHoursTime 的下一個發生時間。計算方式為：PlaceOpeningHoursTime.day的週次、PlaceOpeningHoursTime.time 和 PlaceResult.utc_offset_minutes。如果 PlaceResult.utc_offset_minutes 為 undefined，則 nextDate 為 undefined。

PlacePlusCode interface

google.maps.places.PlacePlusCode 介面

定義地點的開放式位置代碼或「Plus Code」。對於沒有詳細地址的地點，Plus Codes 可用於取代街道地址，例如無編號的建築物或無名街道。
global_code
類型：  string
面積為 1/8000 度 x 1/8000 度的加號代碼。例如 "8FVC9G8F+5W"。
compound_code optional
類型：  string optional
加號地址，面積為 1/8000 度 x 1/8000 度，前四個字元 (區域代碼) 會省略，並替換為地點說明。例如："9G8F+5W Zurich, Switzerland"。如果找不到適合縮短代碼的地區，系統就會省略這個欄位。

PlacePhoto 介面

google.maps.places.PlacePhoto 介面

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

PhotoOptions interface

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」。'en'
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 (含) 之間的數字。