簡介
使用地圖網址，您就可以建立通用的跨平台網址來啟動 Google 地圖並執行搜尋、規劃路線與導航，以及顯示地圖檢視和全景圖片。無論使用何種平台，網址語法都相同。
您不需要 Google API 金鑰，即可使用地圖網址。
通用跨平台語法
無論使用者開啟地圖時使用的平台為何，Android 應用程式、iOS 應用程式或網站的開發人員都可以建構通用網址，開啟 Google 地圖並執行要求動作。
- 使用 Android 裝置：
- 如果已安裝並啟用 Android 版 Google 地圖應用程式，網址會在 Google 地圖應用程式中啟動 Google 地圖，並執行要求的動作。
- 如果未安裝或停用 Google 地圖應用程式，系統會透過瀏覽器啟動 Google 地圖，並執行要求動作。
- 使用 iOS 裝置：
- 如果已安裝 iOS 版 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 - 建立精選清單：啟動 Google 地圖並顯示特定地點清單：
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters - 顯示街景服務全景
：啟動互動式全景圖片：
https://www.google.com/maps/@?api=1&map_action=pano¶meters
重要事項：參數 api=1 會識別這個網址適用的 Maps 網址版本。每項要求都必須提供這個參數。唯一有效的值是 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。
搜尋查詢示例
位置搜尋
在位置搜尋中，您可以使用地點名稱、地址或以半形逗號分隔的經緯度座標搜尋特定位置，結果地圖會在該位置顯示圖釘。這三個範例說明如何使用不同的位置值搜尋相同地點。
範例 1：搜尋地點名稱「Lumen Field」會產生以下地圖：
https://www.google.com/maps/search/?api=1&query=lumen+field
範例 2：僅使用經緯度座標搜尋 Lumen Field，會產生下列地圖。請注意，地圖上會顯示圖釘，但地圖或側邊面板不會提供其他地點資訊：
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
範例 3：使用經緯度座標和地點 ID 搜尋 Lumen Field，會產生以下地圖：
範例 4：搜尋地點名稱「星巴克」會顯示以下地圖：
https://www.google.com/maps/search/?api=1&query=starbucks
範例 5：使用地點名稱和地點 ID 搜尋特定星巴克，會產生以下地圖：
https://www.google.com/maps/search/?api=1&query=starbucks&query_place_id=ChIJsU30zM1qkFQRbnOm1_LBoG0
如果您的目標是顯示特定地點的詳細資料，請使用下列其中一種建議格式建構搜尋網址：
query=PLACE_NAME,ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
如要以程式輔助方式擷取地點 ID，可以使用 Places API：Text Search(ID Only) 功能。 這是取得地點 ID 的免費方法。進一步瞭解地點 ID 和 Place API(新版) 要求。
使用者在地圖上點選或輕觸搜尋點時，也可以擷取地點 ID。進一步瞭解可點選的興趣點圖示 (JavaScript、 Android、 iOS)
類別搜尋
在類別搜尋中，您會傳遞一般搜尋字詞，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：定義顯示路線的起點。預設為最相關的起始位置，例如裝置位置 (如有)。如果沒有，產生的地圖可能會提供空白表單，讓使用者輸入起點。這個值可以是地點名稱、地址，或以半形逗號分隔的經緯度座標。字串應採用 URL 編碼，因此「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：定義路線的終點。如果沒有，產生的地圖可能會提供空白表單，讓使用者輸入目的地。值可以是地點名稱、地址，或以半形逗號分隔的緯度/經度座標。字串應採用 URL 編碼，因此「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(選用)： 定義交通方式。可選項目如下：drivingwalking：盡量使用人行道和騎樓 (如有)。bicycling：盡可能行經單車道。「騎自行車」是指以人力為動力的交通方式。two-wheeler：盡可能規劃兩輪車輛偏好的街道。 「兩輪車」是指兩輪機動車輛，例如摩托車。詳情請參閱「兩輪車涵蓋範圍」。transitdir_action=navigate(選用)：根據是否提供起點，啟動即時路況導航或路線預覽，前往指定目的地。如果使用者指定起點，但該起點與使用者目前所在位置不相近，或目前裝置位置無法使用，地圖會啟動路線預覽畫面。如果使用者未指定起點 (系統會預設為目前裝置所在位置)，或起點與使用者目前所在位置相近，地圖就會啟動即時路況導航。請注意，並非所有 Google 地圖產品都提供導航功能，且導航功能不適用於所有目的地；在這些情況下，系統會忽略這個參數。waypoints：指定一或多個中繼地點，用於規劃origin和destination之間的路線。您可以使用直立線字元 (|) 分隔地點，指定多個路線控點 (例如Berlin,Germany|Paris,France)。允許的路線控點數量會因開啟連結的平台而異，行動瀏覽器最多支援三個路線控點，其他平台最多支援九個路線控點。地圖上顯示路線控點的順序，與網址中列出的順序相同。 每個路線控點可以是地點名稱、位址，或是以半形逗號分隔的經緯度座標。字串應經過 URL 編碼，因此「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) 分隔：ferrieshighwaystolls
travelmode，Google 地圖會根據指定路線和/或使用者偏好設定，顯示一或多種最相關的模式。
路線範例
下列網址會以路線規劃模式啟動地圖，並提供表單讓使用者輸入起點和目的地。
https://www.google.com/maps/dir/?api=1
以下範例會啟動地圖，並顯示從華盛頓州西雅圖太空針塔到派克市場的單車路線。
以下範例會啟動地圖，並顯示從 Google 孟買到孟買國際機場的雙輪車路線。
。
以下範例會啟動地圖，顯示從澳洲 Google 雪梨辦公室到維多利亞女王大廈的步行路線。
顯示地圖
地圖動作會傳回不含標記或路線的地圖。
建立地圖網址
https://www.google.com/maps/@?api=1&map_action=map¶meters
參數
map_action=map(必要)：指定要顯示的地圖檢視畫面類型。地圖和街景服務共用同一個端點。為確保地圖能正常顯示，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
以下範例顯示以澳洲新南威爾斯州卡圖巴為中心的地圖 (位於 -33.712206,150.311941)，並設定選用的 zoom 和 basemap 參數。
顯示街景服務全景
全景動作可讓您啟動檢視器，以互動式全景的形式顯示街景服務圖像。每個街景服務全景都提供單一位置的 360 度完整環景。圖片包含 360 度的水平視圖 (全環景) 與 180 度的垂直視圖 (由正上方到正下方)。全景動作會啟動檢視器，將產生的全景算繪為球體，攝影機則位於其中央。您可以操控攝影機，控制攝影機的縮放及方向。
Google 街景服務可讓您在 涵蓋區域內的指定位置進行全景檢視。此外，您也可以使用使用者提供的光球相片和街景服務特輯。
建立街景服務網址
https://www.google.com/maps/@?api=1&map_action=pano¶meters
參數
map_action=pano(必要)：指定要顯示的檢視畫面類型。地圖和街景服務共用同一個端點。為確保全景顯示，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，是根據拍攝圖片時的攝影機位置設定。因此，傾斜角度 0 通常是水平，但不一定。舉例來說，如果圖片是從山丘上拍攝，其預設傾斜角度可能就不是水平。fov：決定圖片的水平視野。視野範圍以度數表示，範圍為 10 到 100。預設值為 90。 處理固定大小的可視區域時，視野會視為縮放等級，數字越小表示縮放等級越高。
街景服務範例
前兩個範例顯示艾菲爾鐵塔的全景。範例一僅使用 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 街景服務 Image API 提出中繼資料要求。圖片中繼資料要求會提供街景服務全景的相關資料，包括全景 ID。
建立候選清單
精選清單動作會顯示特定地點的清單，使用者可以將這些地點儲存到 Google 地圖個人資料、與他人分享，或個別探索每個地點。
建立候選清單網址
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters
參數
map_action=shortlist(必要)：指定候選清單動作。place_ids(必要)：定義要納入候選清單的地點。這項參數可接受一或多個地點 ID，並以半形逗號分隔。最多可以指定 20 個地點 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:。
使用 Urchin 流量監視器 (UTM) 參數改善 Maps 網址
為協助 Google 進一步瞭解開發人員整合 Maps 網址的方式，並確保最佳效能，建議您在建構網址時加入 Urchin 流量監視器 (UTM) 追蹤參數。加入 utm_source 和 utm_campaign 參數，即可提供寶貴資料，讓我們分析使用模式並改善 Maps URLs 產品。
請在 utm_source 參數中使用應用程式名稱。utm_campaign 參數應反映使用者的預期動作，例如「location_sharing」、「place_details_search」或「directions_request」。
舉例來說，含有 Urchin 流量監視器 (UTM) 參數的網址可能如下所示：
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YOUR_APP_NAME&utm_campaign=place_details_search