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 |
類型：
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 (如有指定)。 |
|
類型：
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
常數
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 代表搜尋地點的嚴格邊界。
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 optionaladr 微格式中地點地址的表示方式。僅適用於 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定義地點的營業時間。 |
|
類型：
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。系統會以以下方式解讀價位：
|
rating optional |
類型：
number optional根據使用者對這個地點的評論，評分介於 1.0 到 5.0。 |
reviews optional |
類型：
Array<PlaceReview> optional這個地點的評論清單。僅適用於 PlacesService.getDetails。 |
types optional |
類型：
Array<string> optional |
url optional |
類型：
string optional這個地點的官方 Google 網頁網址。這是 Google 自有的頁面，內含該地點的實用資訊。僅適用於 PlacesService.getDetails。 |
user_ratings_total optional |
類型：
number optional使用者評分數量，這些評分會影響這個地點的 PlaceResult.rating。 |
|
類型：
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
介面
定義地點的營業時間資訊。
屬性 | |
|---|---|
|
類型：
boolean optional該地點目前是否營業中。 |
periods optional |
類型：
Array<PlaceOpeningHoursPeriod> optional涵蓋每週各天營業時段的陣列，從週日開始，按時間順序排列。不包含地點未營業的日子。僅適用於 PlacesService.getDetails。 |
weekday_text optional |
類型：
Array<string> optional包含七個字串的陣列，以特定格式表示一週內每天的營業時間。地點介面集服務會根據目前語言，正確設定營業時間格式並經過本地化。這個陣列中的元素順序取決於語言。有些語言是以週一做為每週起始日，有些則是週日。僅適用於 PlacesService.getDetails。其他呼叫可能會傳回空陣列。 |
方法 | |
|---|---|
isOpen |
isOpen([date])參數：
傳回值：
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 |
minutes |
類型：
number |
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 紀元時間起算的秒數為單位。 |
|
類型：
Array<PlaceAspectRating> optional評論評分的項目。評分範圍為 0 到 3。 |
author_url optional |
類型：
string optional評論者個人資料的網址。如果無法取得評論者的個人資料，這將是 undefined。 |
rating optional |
類型：
number optional這則評論的評分，介於 1.0 到 5.0 (含) 之間。 |