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 的 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
用來將詳細資料要求與自動完成工作階段結合的專屬 ID。

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 的 Place 搜尋查詢。
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
要求的查詢字詞。例如地點名稱 (「艾菲爾鐵塔」)、類別後方有地點名稱 (「臺北披薩」)，或是地點名稱 (後面加上地點消歧者，例如「雪梨的星巴克」)。
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 常數

「地點搜尋要求」的排名選項。

呼叫 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，並且必須顯示。
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
「地點」的專屬識別碼。
plus_code optional
類型：  PlacePlusCode optional
定義「地點」的「開放地點代碼」，或「加號代碼」。
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 週期，其中包含值為 0 的 day，以及值為 "0000" 的 time，而非 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

google.maps.places.PlacePlusCode 介面

定義「地點」的「開放地點代碼」，或「加號代碼」。Plus Codes 可用於取代所在位置不存在的街道 (非建築物編號，或未命名街道)。
global_code
類型：  string
加號代碼，單位為角度的 1/8000 乘以度數的 1/8000。例如 "8FVC9G8F+5W"。
compound_code optional
類型：  string optional
加號代碼，其中 1/8000 度乘以度數的 1/8000 度，其中前 4 個字元 (區碼) 會遭捨棄且被地區說明取代。例如："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（含）。