Places Service

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

PlacesService 類別

google.maps.places.PlacesService 類別

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

必須提供 &libraries=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 的地點詳細資料查詢。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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 搜尋查詢。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

bounds 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 的文字搜尋要求。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

bounds optional
搜尋地點時用於調整結果的邊界 (選用)。如果設定了 bounds,則系統會忽略 locationradius。這些結果不會侷限於這些範圍內,但會影響其結果。
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 的排名選項。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

DISTANCE 系統會依據所在位置與位置之間的排名結果。
PROMINENCE 排名會影響結果的顯眼程度。

LocationBias typedef

google.maps.places.LocationBias typedef

LocationBias 代表在搜尋地點時要使用的軟邊界或提示。結果可能來自指定區域。如要將目前使用者的 IP 位址當做偏誤,您可以指定 "IP_BIAS" 字串。注意:如果使用 Circle,則必須定義中心和半徑。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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

LocationRestriction typedef

google.maps.places.LocationRestriction typedef

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

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

LatLngBounds|LatLngBoundsLiteral

PlacesServiceStatus 常數

google.maps.places.PlacesServiceStatus 常數

PlacesService 完成搜尋時傳回的狀態。請依據值或使用常數名稱來指定這些參數。例如 'OK'google.maps.places.PlacesServiceStatus.OK

必須提供 &libraries=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 介面介面

用於擷取其他「地點」結果頁面的物件。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

hasNextPage
類型:boolean
指出是否有其他結果。如果有其他搜尋結果網頁,請true
nextPage
nextPage()
參數:
傳回值:
擷取下一頁的結果。使用與第一次搜尋要求相同的回呼函式。

PlaceResult 介面

google.maps.places.PlaceResult 介面介面

定義地點相關資訊。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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
用於 Place' 圖示的背景顏色。另請參閱 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
定義地點的開放式地點代碼或「加號代碼」
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 介面介面

定義使用者評論地點相關資訊。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

rating
類型:number
這個面向的評分。個別評論的整數為 0 到 3 之間的整數。對於地點的累計評分,這個值是 0 到 30 之間的整數。
type
類型:string
長寬比類型。例如,"food""decor""service""overall"

BusinessStatus 常數

google.maps.places.BusinessStatus 常數

「地點」的營運狀態 (如果是商家),則會在 PlaceResult 中傳回 (指出地點是否營業,或暫時或永久停業)。請依值或常數名稱 (例如 'OPERATIONAL'google.maps.places.BusinessStatus.OPERATIONAL) 進行指定。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

CLOSED_PERMANENTLY 商家已永久停業。
CLOSED_TEMPORARILY 該商家目前暫停營業。
OPERATIONAL 商家運作正常。

PlaceGeometry 介面

google.maps.places.PlaceGeometry 介面介面

定義地點幾何圖形的相關資訊。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

location optional
類型:LatLng optional
地點的位置。
viewport optional
類型:LatLngBounds optional
在地圖上顯示這個地點的偏好可視區域。如果不明地點的可視區域,此屬性為 null。僅適用於 PlacesService.getDetails

PlaceOpeningHours 介面

google.maps.places.PlaceOpeningHours 介面介面

定義地點的營業時間資訊。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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 週期,其中包含值為 0day,以及值為 "0000"time,而非 close

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

open
「地點」的營業時間。
close optional
類型:PlaceOpeningHoursTime optional
「地點」的關閉時間。

PlaceOpeningHoursTime介面

google.maps.places.PlaceOpeningHoursTime 介面介面

定義地點的開啟或關閉時間。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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.dayPlaceOpeningHoursTime.timePlaceResult.utc_offset_minutes。如果 PlaceResult.utc_offset_minutesundefined,則 nextDateundefined

PlacePlusCode 介面

google.maps.places.PlacePlusCode 介面介面

定義地點的開放式郵遞區號或「加號代碼」。如果地點不存在或沒有命名街道,可以改用 Plus Codes 取代街道地址。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

global_code
類型:string
加號代碼,書寫度為 1/8000 x 1/8000 度。例如 "8FVC9G8F+5W"
compound_code optional
類型:string optional
捨棄度數為 1/8000 的學區 1/8000 的 plus code,將地點前四個字元 (區碼) 捨棄,並以地區說明取代。例如,"9G8F+5W Zurich, Switzerland"。如果找不到可以縮短程式碼的適當區域,系統會省略這個欄位。

PlacePhoto 介面

google.maps.places.PlacePhoto 介面介面

代表地點的相片元素。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

height
類型:number
相片的高度,以像素為單位。
html_attributions
類型:Array<string>
針對這張相片中顯示的歸因文字。
width
類型:number
相片的寬度 (以像素為單位)。
getUrl
getUrl([opts])
參數:
傳回值:string
傳回與指定選項相對應的圖片網址。

PhotoOptions 介面

google.maps.places.PhotoOptions 介面介面

用於定義相片要求選項。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

maxHeight optional
類型:number optional
傳回圖片的高度上限 (以像素為單位)。
maxWidth optional
類型:number optional
傳回圖片的寬度上限 (以像素為單位)。

PlaceReview 介面

google.maps.places.PlaceReview 介面介面

代表某地點的評論。

必須提供 &libraries=places 網址參數。請參閱 Maps JavaScript API 中的程式庫

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