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)
參數: 
傳回值:
根據關鍵字或類型,擷取特定位置附近的地點清單。您必須透過傳遞 LatLngBoundslocationradius 參數來指定位置。傳遞至回呼的 PlaceResult 是完整 PlaceResult 的子集。只要傳送 Place Details 要求,傳遞所需地點的 PlaceResult.place_id,應用程式就能取得每個地點的詳細 PlaceResultPlaceSearchPagination 物件可用於擷取其他結果頁面 (如果這是最後一頁,或只有一頁結果,則為空值)。
textSearch
textSearch(request, callback)
參數: 
傳回值:
根據查詢字串 (例如「臺北披薩」或「渥太華附近的鞋店」) 擷取地點清單。位置參數為選用項目;指定位置時,結果只會偏向附近的結果,不會限制顯示區域內的地點。當您想使用任意字串搜尋地點,且不想將搜尋結果限制在特定位置時,請使用 textSearchPlaceSearchPagination 物件可用於擷取其他結果頁面 (如果這是最後一頁,或只有一頁結果,則為空值)。

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,系統會忽略 locationradius
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,但無法指定 radiusbounds
type optional
類型:  string optional
搜尋指定類型的地點。類型會轉譯為要求目標地區的當地語言,並做為查詢字串使用。如果同時提供查詢,該查詢會串連為本地化的類型字串。回應中會捨棄其他類型的結果。這個欄位可用於執行不同語言及地區獨立的類別搜尋。有效的類型請參閱這裡

TextSearchRequest 介面

google.maps.places.TextSearchRequest 介面

要傳送到 PlacesService 的文字搜尋要求。

bounds optional
類型:  LatLngBounds|LatLngBoundsLiteral optional
用來在搜尋地點時自訂調整結果的邊界 (選用)。如果設定 bounds,系統會忽略 locationradius。結果不會僅限於這些邊界內的結果,但內部結果的排名會較高。
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])
參數: 
  • dateDate optional
傳回值:  boolean|undefined
查看地點是否營業中 (未註明日期時),或是否在指定日期營業。如果這個地點沒有 PlaceResult.utc_offset_minutesPlaceOpeningHours.periods,則會傳回 undefined (PlaceOpeningHours.periods 只能透過 PlacesService.getDetails)。這個方法不會考慮特殊營業時間,例如假日營業時間。

PlaceOpeningHoursPeriod 介面

google.maps.places.PlaceOpeningHoursPeriod 介面

定義地點營業時間的結構化資訊。注意:如果地點全年無休,回應中會缺少 close 部分。用戶端可以將「持續開啟」表示為 open 時段,其中包含 day (值為 0time) 的值 ("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.dayPlaceOpeningHoursTime.timePlaceResult.utc_offset_minutes 計算而得。如果 PlaceResult.utc_offset_minutesundefined,則 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 (含) 之間。