簡介
使用地圖網址,您就可以建立通用的跨平台網址來啟動 Google 地圖並執行搜尋、規劃路線與導航,以及顯示地圖檢視和全景圖片。 無論使用何種平台,網址語法都相同。
就算沒有 Google API 金鑰,也能使用 Google 地圖網址。
通用跨平台語法
無論是 Android 應用程式、iOS 應用程式或網站開發人員,都可以建構通用網址,這樣無論使用何種平台,開啟地圖時,系統都會開啟 Google 地圖並執行要求的動作。
- 在 Android 裝置上:
- 如果已安裝 Android 版 Google 地圖應用程式,且已啟用,該網址會在 Google 地圖應用程式中開啟 Google 地圖,並執行要求的動作。
- 如果未安裝或停用 Google 地圖應用程式,網址會在瀏覽器中啟動 Google 地圖,並執行要求的動作。
- 在 iOS 裝置上:
- 如果已安裝 iOS 版 Google 地圖應用程式,網址會在 Google 地圖應用程式中啟動 Google 地圖,並執行要求的動作。
- 如果未安裝 Google 地圖應用程式,網址會在瀏覽器中啟動 Google 地圖,並執行要求的動作。
- 在任何其他裝置上,網址會在瀏覽器中啟動 Google 地圖,並執行要求的動作。
建議您使用跨平台網址,從您的應用程式或網站啟動 Google 地圖,因為無論使用哪種平台,這些通用網址都能能更廣泛處理地圖要求。如果是只能在行動平台上運作的功能 (例如即時路線導航),建議您針對 Android 或 iOS 使用特定平台的選項。請參閱下列說明文件:
- 適用於 Android 的 Google 地圖意圖:專門用來啟動 Android 版 Google 地圖應用程式
- iOS 版 Google 地圖網址配置:專門用來推出 iOS 版 Google 地圖應用程式
啟動 Google 地圖並執行特定動作
如要啟動 Google 地圖,並視需要執行其中一種支援的函式,請依據所要求的動作,使用下列其中一種格式的網址配置:
- 搜尋 - 啟動顯示特定地點圖釘的 Google 地圖,或執行一般搜尋並顯示地圖結果:
https://www.google.com/maps/search/?api=1¶meters
- 路線
- 要求規劃路線並啟動 Google 地圖,包含以下結果:
https://www.google.com/maps/dir/?api=1¶meters
- 顯示地圖 - 啟動不含標記或路線的 Google 地圖:
https://www.google.com/maps/@?api=1&map_action=map¶meters
- 顯示街景服務全景 — 啟動互動式全景圖片:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
重要事項:api=1
參數可指明這個網址的目標 Google 地圖網址版本。每次要求都必須提供這個參數。唯一的有效值是 1。如果網址中「未」包含 api=1
,系統會忽略所有參數,並在瀏覽器或 Google 地圖行動應用程式中啟動預設的 Google 地圖應用程式 (視使用中的平台而定,例如 https://www.google.com/maps)。
建立有效網址
您必須正確編碼網址。
舉例來說,部分參數使用直立線字元 (|
) 做為分隔符,因此您必須在最終到達網址中以 %7C
編碼。其他參數會使用以半形逗號分隔的值,例如經緯度座標或「城市、州/省」。您必須將半形逗號編碼為 %2C
。請使用 %20
將空格編碼,或是以加號 (+
) 取代。
此外,每個要求的網址上限為 2,048 個字元。建構網址時,請注意這項限制。
Google 地圖動作
可用的地圖動作有:搜尋、規劃路線、顯示地圖,以及顯示街景服務全景。您可以在要求網址中指定動作,以及必要和選用參數。如同網址標準,您可以使用 & 字元 (&
) 分隔參數。「搜尋參數」部分會列出參數清單及可能的值。
搜尋
搜尋動作會顯示所有可見地圖區域內的搜尋結果。當您搜尋特定地點時,產生的地圖會在指定位置放置圖釘,並顯示可用地點詳細資料。
建立搜尋網址
https://www.google.com/maps/search/?api=1¶meters
參數
query
(必要):定義要在地圖上醒目顯示的地點。所有搜尋要求都必須設有查詢參數。query_place_id
(選用):地點 ID 是用來識別特定地點的文字 ID,針對search
動作,您必須指定query
,但也可以指定query_place_id
。如果同時指定這兩個參數,只有在 Google 地圖找不到地點 ID 時,才會使用query
。如果您要明確連結至特定建築物,地點 ID 最好能夠連結至正確的地點。此外,當您使用經緯度座標查詢特定位置時,也建議提交query_place_id
。
搜尋範例
位置搜尋
在位置搜尋中,您可以使用地點名稱、地址或以半形逗號分隔的經緯度座標搜尋特定地點,結果地圖就會在該位置顯示圖釘。這三個範例說明瞭使用不同位置值搜尋相同地點「CenturyLink Field」(即華盛頓州西雅圖的體育場) 的搜尋。
範例 1:搜尋地點名稱「CenturyLink Field」會產生以下地圖:
https://www.google.com/maps/search/?api=1&query=centurylink+field
範例 2:使用經緯度座標搜尋 CenturyLink 欄位,以及地點 ID 結果,以下地圖顯示結果:
範例 3:如果只使用經緯度座標搜尋 CenturyLink 欄位,以下地圖中會顯示結果。請注意,地圖中有一個圖釘,但地圖或側邊面板中並未提供其他地點資訊:
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
類別搜尋
在類別搜尋中,您必須傳送一般搜尋字詞,Google 地圖會嘗試在接近指定地區附近尋找符合指定條件的商家資訊。如未指定地點,Google 地圖會嘗試尋找您目前所在位置附近的商家資訊。如要提供地點以搜尋類別搜尋,請在一般搜尋字串中加入位置,例如 pizza+seattle+wa
。
在這個範例中,搜尋華盛頓州西雅圖的披薩餐廳時,產生的地圖如下:
https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa
規劃路線
路線規劃動作會顯示地圖上兩個指定點之間的路徑,以及距離和行程時間。
設定路線網址結構
https://www.google.com/maps/dir/?api=1¶meters
參數
origin
:定義顯示路線的起點。預設為最相關的起點位置,例如裝置位置 (如有)。如果沒有,結果地圖可能會提供空白表單,讓使用者輸入起點。這個值可以是地點名稱、地址或以半形逗號分隔的經緯度座標。字串必須進行網址編碼,因此「City Hall, New York, NY」等地址應轉換為City+Hall%2C+New+York%2C+NY
。注意:除非您在網址中指定
origin_place_id
,否則此為選用參數。如果選擇指定origin_place_id
,也必須在網址中加入origin
。origin_place_id
(選用):地點 ID 是用來識別特定地點的文字 ID,如要明確指定建築物,使用地點 ID 最好能夠確實連結至正確的地點。使用這個參數的網址也必須包含origin
。destination
:定義路線的端點。如果沒有,結果地圖可能會提供空白表單,讓使用者進入目的地。這個值可以是地點名稱、地址或以半形逗號分隔的經緯度座標。字串必須進行網址編碼,因此「City Hall, New York, NY」等地址應轉換為City+Hall%2C+New+York%2C+NY
。注意:除非您在網址中指定
destination_place_id
,否則此為選用參數。如果選擇指定destination_place_id
,也必須在網址中加入destination
。destination_place_id
(選用):地點 ID 是用來識別特定地點的文字 ID,如要明確指定建築物,使用地點 ID 最好能夠確實連結至正確的地點。使用這個參數的網址也必須包含destination
。travelmode
(選用):定義交通方式,選項包括driving
、walking
(建議使用人行道和人行道,如果可使用)、bicycling
(可能設有單車道和專用道路的路線) 或transit
。如未指定travelmode
,Google 地圖會根據指定路線和/或使用者偏好設定,顯示一或多個最相關的模式。dir_action=navigate
(選用):根據是否有可用起點,啟動前往指定目的地的即時路線導航或路線預覽。如果使用者指定的起點並未與使用者的目前位置相近,或是無法取得當前裝置的位置資訊,地圖就會啟動路線預覽。如果使用者未指定起點 (情況下,起點預設為目前的裝置位置),或者起點靠近使用者目前的位置,地圖就會啟動即時路線導航。請注意,並非所有 Google 地圖產品及/或所有目的地之間都提供導航功能;在這種情況下,系統會忽略這個參數。waypoints
:在origin
和destination
之間,指定用於規劃路線的一或多個中介地點。您可以使用直立線字元 (|
) 來分隔地點 (例如Berlin,Germany|Paris,France
)。可用的路線控點數量因連結開啟的平台而異,行動瀏覽器最多支援三個路線控點,另有最多支援九個路線控點。路線控點在地圖上的顯示順序與在網址中的順序相同。每個路線控點可以是地點名稱、地址,或以半形逗號分隔的經緯度座標。字串必須進行 網址編碼,因此「柏林,德國|巴黎,法國」等路線控點應轉換為Berlin%2CGermany%7CParis%2CFrance
。附註:
- Google 地圖產品都不支援路線控點;如果符合這些條件,系統就會忽略這個參數。
- 除非您在網址中指定
waypoint_place_ids
,否則此為選用參數。如果選擇指定waypoint_place_ids
,就必須在網址中加入waypoints
。
waypoint_place_ids
(選用):地點 ID 是用來識別特定地點的文字 ID,Waypoint_place_ids
可讓您提供地點 ID 清單,以便與waypoints
清單比對。 地點 ID 的順序應與路線控點相同,並以直立線字元「|
」( 網址編碼為%7C
) 進行分隔。如果您要明確指定特定建築物,地點 ID 最好確保您連結到正確的地點。使用這個參數的網址也必須包含waypoints
。avoid
(選用):設定路徑應盡可能避免的地圖項目。這個屬性可設為一或多個以下一或多個選項,中間以半形逗號字元「,
」( 網址編碼為%2C
) 分隔:ferries
highways
tolls
導航範例
下列網址會在路線模式中啟動地圖,並提供表單讓使用者輸入起點和目的地。
https://www.google.com/maps/dir/?api=1
以下範例會啟動一份地圖,其中包含從華盛頓州西雅圖的太空針塔到派克市場 (Pike Place Market) 的單車路線。
下例啟動地圖,其中包含從 Google 在澳洲雪梨到維多利亞女王大廈的步行路線。
顯示地圖
地圖動作會傳回不含標記或路線的地圖。
設定地圖網址
https://www.google.com/maps/@?api=1&map_action=map¶meters
參數
map_action=map
(必要):指定要顯示的地圖檢視類型。Google 地圖和街景服務共用同一個端點。為確保顯示地圖,必須將map_action
指定為map
。center
(選用):定義地圖視窗的中心,並接受以逗號分隔的經緯度座標 (例如-33.8569,151.2152
)。zoom
(選用):設定地圖的初始縮放等級。系統接受的值是介於 0 (全世界) 到 21 (個別建築物) 的整數。上限可能因所選位置可用的地圖資料而異。預設值為 15。basemap
(選用):定義要顯示的地圖類型,這個值可以是roadmap
(預設值)、satellite
或terrain
。layer
(選用):定義要在地圖上顯示的額外圖層 (如有)。這個值可以是下列任一值:none
(預設)、transit
、traffic
或bicycling
。
地圖範例
此範例網址會啟動預設以使用者目前位置為中心的 Google 地圖。
https://www.google.com/maps/@?api=1&map_action=map
下例顯示以 Katoomba、NSW、澳洲 (-33.712206,150.311941
) 為中心的地圖,並設定選用的 zoom
和 basemap
參數。
顯示街景服務全景
這個全景操作可讓您啟動檢視器,將街景服務圖片顯示為互動式全景。每個街景服務全景都提供單一位置的 360 度完整環景。圖片包含 360 度的水平視圖 (全環景) 與 180 度的垂直視圖 (由正上方到正下方)。全景動作會啟動檢視器,將產生的全景算繪為球體,相機則位於其中央。您可以操控相機,控制攝影機的縮放和方向。
Google 街景服務可讓您在指定地點的 涵蓋區域一覽無遺的全景。您也可以使用使用者提供的全景相片和街景服務集錦。
建立街景服務網址
https://www.google.com/maps/@?api=1&map_action=pano¶meters
參數
map_action=pano
(必要):指定要顯示的檢視畫面類型。Google 地圖和街景服務共用同一個端點。如要確保顯示全景,必須將action
指定為pano
。
您也必須使用下列其中一個網址參數:
viewpoint
:檢視器會顯示最靠近viewpoint
地點的全景,並用逗號分隔的經緯度座標指定,例如 46.414382,10.013988。由於街景服務圖像會定期更新,而且每次拍攝的位置可能略有不同,因此在更新圖像後,該地點可能會對齊不同的全景。pano
:要顯示的特定圖片全景 ID。如果指定pano
,也可以一併指定viewpoint
。只有在 Google 地圖找不到全景 ID 時,才能使用viewpoint
。如果指定了pano
但找不到,且「未」指定viewpoint
,則不會顯示全景圖片。Google 地圖會改為以預設模式開啟,並以使用者目前所在位置為中心顯示地圖。
下列是自選網址參數:
heading
:表示從北方順時針方向相機的指南針方向。可接受的值為 -180 到 360 度。如果省略標題,系統會根據查詢的觀點 (如有指定) 和圖片的實際位置,選擇預設標題。pitch
:指定相機的角度、向上或向下。傾斜度是以 -90 到 90 之間的度數表示。正值會將攝影機朝上傾斜,負值則會使攝影機向下角度。預設傾斜角度是根據相機拍攝時的位置而定。因此,音高為 0 通常是水平,但不一定都是水平。舉例來說,在山上拍攝的圖片中,預設傾斜角度可能就不是水平。fov
:決定圖片的水平視野。視野是以度數表示,範圍介於 10 到 100 之間。預設值為 90。處理固定大小的可視區域時,系統會將視野視為縮放等級,數字越小表示縮放等級較高。
街景服務範例
前兩個範例會顯示艾菲爾鐵塔的全景。範例 1 僅針對位置使用 viewpoint
,並設定選用的 heading
、pitch
和 fov
參數。為進行比較,範例兩個會使用 pano
ID 和第一個範例中設定的相同參數。第三個範例會顯示室內全景圖片。
範例 1:只使用 viewpoint
指定位置。
範例 2:使用 pano
ID 和 viewpoint
位置。pano
ID 的優先順序高於 viewpoint
。在這個範例中,已找到全景 ID,因此會忽略 viewpoint
。請注意,pano
ID 顯示的全景圖片與僅使用 viewpoint
的圖片不同,最近也略有不同。
範例 3:顯示英國倫敦 Sarastro 餐廳的內部全景,並指定全景 ID。
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
尋找全景 ID
您可以使用多種方法找出特定全景圖片的 ID。
- 如果是 JavaScript,請使用 StreetViewPanorama 類別。
- 如果是 Android,請使用公開類別 StreetViewPanoramaLocation。
- 如果是 iOS,請使用 GMSPanorama 類別。
- 您也可以 使用 Google Street View Image API 提出中繼資料要求。圖片中繼資料要求提供街景服務全景相關資料,包括全景 ID。
其他示例
使用路線控點的路線範例
下列路線範例會啟動 Google 地圖,並顯示從法國巴黎到法國雀爾堡的行車路線,並通過下列路線控點:
國家/地區,城市 | 地點名稱 | 地點 ID |
---|---|---|
1. 法國凡爾賽 | 凡爾賽宮 | ChIJdUyx15R95kcRj85ZX8H8OAU |
2. 法國夏特勒 | 查特雷斯大教堂 | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
3. 法國利曼 | 聖朱利安主教座堂 | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
4. 法國康本 | 康城 | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
在範例網址中,路線控點會以不同的方式定義,因此您可以在結果地圖上比較路線控點的顯示方式。
範例 1:路線控點定義為城市、國家/地區:
範例 2:定義為特定地點名稱的路線控點:
範例 3:定義為城市、國家/地區的路線控點,並針對各個路線控點提供特定建築物的 waypoint_place_ids
:
範例 4:將路線控點定義為城市、國家/地區,但路線控點的順序與上一個範例不同。示範地圖按照網址所列順序顯示路線控點。
地圖範例
顯示具有指定 basemap
(衛星) 和 layer
(大眾運輸) 的地圖。
街景服務範例
使用 FIFE 圖片鍵做為 pano
ID,顯示街景服務全景。請注意,pano
ID 的前面會加上 F:。