Places Service

PlacesService 類別

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 的地點詳細資料查詢。
placeId
類型：string
要求詳細資料的地點 ID。
fields optional
類型：Array<string> optional
詳細資料回應中要加入的欄位，並會計費。如果未指定任何欄位，或已傳入 ['ALL']，系統會傳回所有可用的欄位並據此收費 (不適用於實際工作環境部署作業)。如需欄位清單，請參閱 PlaceResult。巢狀欄位可使用點號路徑 (例如 "geometry.location") 指定。
language optional
類型：string optional
應傳回詳細資料的語言代碼。請參閱支援語言清單。
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
應傳回姓名和地址時所用的語言語言識別碼 (如果有的話)。請參閱支援語言清單。
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
用於搜尋地點的邊界。如果設定 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 介面

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 介面

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 code」。對於沒有詳細地址的地點，Plus Codes 可用於取代街道地址，例如無編號的建築物或無名街道。
global_code
類型：string
一個 plus code，當中含有度數 1/8000 度的 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 介面

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 (含) 之間。