開始使用

簡介

使用地圖網址,您就可以建立通用的跨平台網址來啟動 Google 地圖並執行搜尋、規劃路線與導航,以及顯示地圖檢視和全景圖片。無論使用的平台為何,網址語法都相同。

您不需要 Google API 金鑰就能使用地圖網址。

通用跨平台語法

身為 Android 應用程式、iOS 應用程式或網站的開發人員,您可以建立通用網址,如此一來,無論地圖開啟了哪個平台,即會開啟 Google 地圖並執行要求的動作。

  • 使用 Android 裝置:
    • 只要安裝並啟用 Google 地圖應用程式 Android 版,網址就會在 Google 地圖應用程式中開啟 Google 地圖,並執行要求的動作。
    • 如未安裝或停用 Google 地圖應用程式,網址會在瀏覽器中啟動 Google 地圖,並執行所要求的動作。
  • 使用 iOS 裝置:
    • 如果已安裝 iOS 版 Google 地圖應用程式,網址就會在 Google 地圖應用程式中啟動 Google 地圖,並執行所要求的動作。
    • 如未安裝 Google 地圖應用程式,網址將在瀏覽器中啟動 Google 地圖並執行要求的動作。
  • 在其他裝置上,網址會在瀏覽器中啟動 Google 地圖,並執行所要求的動作。

建議您使用跨平台網址,從您的應用程式或網站啟動 Google 地圖,因為無論使用哪個平台,這類通用網址都能提供更多處理地圖要求。針對可能僅適用於行動平台的功能 (例如即時路線導航),您可能會想要使用 Android 或 iOS 專用的平台專用選項。請參閱下列說明文件:

啟動 Google 地圖並執行特定動作

若要啟動「Google 地圖」並且選擇性執行其中一個支援的函式,請根據所要求的動作,使用下列其中一種表單的網址配置:

  • 搜尋 — 啟動 Google 地圖,用來顯示特定地點的圖釘,或執行一般搜尋並啟動地圖以顯示結果:
    https://www.google.com/maps/search/?api=1&parameters
  • 路線 — 要求取得路線並啟動 Google 地圖,並提供以下結果:
    https://www.google.com/maps/dir/?api=1&parameters
  • 顯示地圖 — 啟動 Google 地圖,不加入任何標記或規劃路線:
    https://www.google.com/maps/@?api=1&map_action=map&parameters
  • 顯示街景服務全景 — 啟動互動式全景圖片:
    https://www.google.com/maps/@?api=1&map_action=pano&parameters

重要事項api=1 參數可識別這個網址所代表的「地圖」網址版本。每個要求都需要這個參數。唯一有效的值為 1。如果網址包含 api=1,則系統會略過所有參數,並依預設使用的平台 (例如 https://www.google.com/maps),在瀏覽器或 Google 地圖行動應用程式中啟動預設的 Google 地圖應用程式。

建立有效網址

您必須妥善編碼網址。

舉例來說,某些參數使用直立線字元 (|) 做為分隔符,您必須在最終到達網址中將編碼編碼為 %7C。其他參數會使用以逗號分隔的值,例如緯度/經度座標或城市、州。您必須將逗號編碼為 %2C。使用 %20 來編碼空格,或用加號 (+) 取代空格。

此外,每個請求的網址上限為 2,048 個字元。建立網址時,請留意這項限制。

地圖操作

可用的地圖動作包括:搜尋、規劃路線、顯示地圖,以及顯示街景服務全景。您可以在要求網址中指定動作,以及必要和選用參數。如同網址的標準,您可以使用 & 字元 (&) 來分隔參數。「搜尋參數」部分會列舉每個動作的參數清單及其可能的值。

搜尋

搜尋動作會針對可見的地圖區域顯示一項搜尋結果。搜尋特定地點時,產生的地圖會在指定位置放置圖釘,並顯示可用的地點詳細資料。

建立搜尋網址

https://www.google.com/maps/search/?api=1&parameters

參數

  • query (必填):定義要在地圖上標明的地點。所有搜尋要求都必須使用查詢參數。
    • 請將地點指定為地點名稱、地址,或以逗號分隔的經緯度座標。字串應採用網址編碼,因此「City Hall, New York, NY」等地址應轉換為 City+Hall%2C+New+York%2C+NY
    • URL 編碼的字串指定一般搜尋字詞,例如 grocery+storesrestaurants+in+seattle+wa
  • 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,結果如下圖所示:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

範例 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&parameters

參數

  • 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 (選用):定義交通方式。選項包括 drivingwalking (偏好行人步道和人行道)、bicycling (提供單車道與路徑的街道) 或 transit。如未指定 travelmode,Google 地圖會顯示指定路線和/或使用者偏好設定的一或多個相關模式。
  • dir_action=navigate (選用):根據來源是否可用,啟動即時路線導航或路線預覽至指定目的地。如果使用者指定出發地,但並不接近使用者目前的位置,或是目前裝置位置無法使用,地圖就會啟動路線預覽。如果使用者沒有指定起點 (這時起點會預設為目前裝置的位置),或者起點靠近使用者的目前位置,地圖就會啟動即時路線導航功能。請注意,並非所有 Google 地圖產品和/或所有目的地都提供導航功能,在這種情況下,系統會忽略這個參數。
  • waypoints:指定一或多個中介地點,以在 origindestination 之間規劃路線。如要指定多個路線控點,請使用直立線字元 (|) 來分隔不同地點 (例如 Berlin,Germany|Paris,France)。可用的路徑點數量會因連結開啟的平台而有所不同,行動瀏覽器中最多支援 3 個路線控點;如果不支援,最多支援 9 個路線控點。路線控點的顯示順序會依照在網址中列出的順序。 每個路線控點可以是地點名稱、地址或以逗號分隔的經緯度座標。字串應採用網址編碼,因此「Berlin, Germanyy|Paris,France」等路線控點應轉換為 Berlin%2CGermany%7CParis%2CFrance

    注意事項:

    • 部分 Google 地圖產品都不支援路線控點;在這種情況下,系統會忽略這個參數。
    • 除非您在網址中指定 waypoint_place_ids,否則此為必要參數。如果您選擇指定 waypoint_place_ids,就必須在網址中加入 waypoints
  • waypoint_place_ids (選用):地點 ID 是用來識別特定地點的文字 ID。Waypoint_place_ids 可讓您提供與 waypoints 清單相符的地點 ID 清單。 地點 ID 的順序應與路線控點相同,並以直立線字元「|」(以網址編碼%7C) 來分隔。如果您正要明確指定某些建築物,使用地點 ID 是最適當的連結,可以確保您會連結到正確的地點。使用這個參數的網址也必須包含 waypoints

路線範例

下方網址會啟動導航模式的地圖,並提供一份表單,讓使用者可以進入起點和目的地。

https://www.google.com/maps/dir/?api=1

下列範例會啟動地圖,顯示從「太空針塔」到「華盛頓州西雅圖市 Pike Place Market」的單車路線。

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

下方範例會啟動地圖,顯示從 Google 前往澳洲雪梨、皇后大樓的步行路線,範圍為澳洲皇后區的步行路線。

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking


顯示地圖

地圖動作會傳回不含標記或路線的地圖。

建立地圖網址

https://www.google.com/maps/@?api=1&map_action=map&parameters

參數

  • map_action=map (必要):指定要顯示的地圖檢視類型。地圖和街景服務共用同一個端點。為了確保地圖顯示,map_action 必須指定為 map
  • center (選用):定義地圖視窗的中心點,並以經緯度值做為逗號分隔值 (例如 -33.8569,151.2152)。
  • zoom (選用):設定地圖的初始縮放等級。 系統接受的值為 0 (全球) 至 21 (個別建築物) 之間的整數,而上限會因所選位置的可用地圖資料而異。預設值為 15。
  • basemap (選用):定義要顯示的地圖類型。這個值可以是 roadmap (預設值)、satelliteterrain
  • layer (選用):定義要在地圖上顯示額外圖層 (如有)。這個值可以是下列任一值:none (預設值)、transittrafficbicycling

地圖範例

這個範例網址會啟動預設 Google 地圖,並以使用者目前所在位置為中心。

https://www.google.com/maps/@?api=1&map_action=map

以下範例顯示以澳洲新南威爾斯州卡塔姆巴市為地圖 (位於 -33.712206,150.311941) 的地圖,並設定選用的 zoombasemap 參數。

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain


顯示街景服務全景

全景操作可啟動檢視器,將街景服務圖片顯示為互動式全景。每個街景服務全景都可讓您透過單一位置提供完整的 360 度環景。 圖片包含 360 度的水平視圖 (完整的環景) 與 180 度的垂直視圖 (由正上方到正下方)。全景操作會啟動一個檢視器,將產生的全景轉譯為球體,相機則位於其中央。您可以藉由操控相機,控制相機的縮放及方向。

Google 街景服務可讓您在指定涵蓋範圍區域的指定位置提供全景。您也可以使用使用者提供的 全景相片街景服務特殊集錦

建立街景服務網址

https://www.google.com/maps/@?api=1&map_action=pano&parameters

參數

  • 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。處理固定大小的可視區域時,檢視畫面欄位會視為縮放等級,而較小的數值表示較高的縮放等級。

街景服務範例

前兩個範例顯示艾菲爾鐵塔的全景。範例 1 僅使用 viewpoint 做為位置,並設定選用的 headingpitchfov 參數。為方便比較,範例 2 使用 pano 以及第一個範例中設定的參數。第三個示例是室內全景圖片,

範例 1:只使用 viewpoint 來指定位置。

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

範例 2:使用 pano ID 和 viewpoint 位置。pano ID 的優先順序高於 viewpoint。 在本範例中,系統會找到全景 ID,因此會忽略 viewpoint。請注意,pano ID 顯示的全景圖片與只使用 viewpoint 找到的圖片稍有不同,而且較新。

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

範例 3:顯示英國倫敦莎薩斯特餐廳內部的全景,並以全景 ID 指定。

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

尋找全景 ID

如要尋找特定全景圖的 ID,可以使用多種方法。

其他示例

使用路線控點的導航範例

下列路線範例會啟動 Google 地圖,並顯示從法國巴黎至法國切爾本 (Grbourg) 的行車路線,規劃下列路線控點:

國家/地區,城市地點名稱地點 ID
1. 法國凡爾賽 凡爾賽宮 ChIJdUyx15R95kcRj85ZX8H8OAU
2. 法國查特爾 沙特主教座堂 ChIJKzGHdEgM5EcR_OBTT3nQoEA
3. 法國勒芒 聖馬利安聖馬利安大教堂 ChIJG2LvQNCI4kcRKXNoAsPi1Mc
4. 法國卡恩 康城 ChIJ06tnGbxCCkgRsfNjEQMwUsc

在示例網址中,路線控點會以不同方式定義,因此您可以比較路線上路線點的顯示方式差異。

範例 1:路線控點定義為城市、國家/地區:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

範例 2:路線控點定義為特定地點名稱:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

範例 3:路線控點定義為城市、國家/地區,並提供每個路線控點的特定建築物的 waypoint_place_ids

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

範例 4:將路線控點定義為城市、國家/地區,但與路線範例相比,路線順序不同。證明地圖會按照路線中所列的順序顯示路線控點。

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

地圖範例

顯示具有指定 basemap (衛星) 和 layer (大眾運輸) 的地圖。

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

街景服務範例

使用 FIFE 圖片金鑰做為 pano ID,顯示街景服務全景。請注意,pano ID 的前面會加上 F:

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55