Google 地圖網址架構 (iOS)

在搭載 iOS 9 以上版本的裝置上，如果您有 Google 地圖網址，可以使用通用連結啟動 Google 地圖。

您可以使用 Google 地圖網址配置來啟動 Google 地圖應用程式 iOS 版，並執行搜尋、取得路線要求，以及顯示地圖檢視畫面。啟動 Google 地圖時，系統會自動將套件 ID 傳送至要求。

您不需要 Google API 金鑰，即可使用 Google 地圖網址配置。

通用連結和 Google 地圖

iOS 版 Google 地圖支援搭載 iOS 9 以上版本的裝置的通用連結。

如果網址符合下列規則運算式，且裝置搭載 iOS 9 以上版本，建議您直接使用 openURL: 方法。

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

例如：

UIApplication.shared.openURL(URL(string:"https://www.google.com/maps/@42.585444,13.007813,6z")!)

[[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"https://www.google.com/maps/@42.585444,13.007813,6z"]];

總覽

網址通訊協定可讓您從其他 iOS 應用程式或網頁應用程式啟動原生 iOS 應用程式。您可以在網址中設定選項，這些選項會傳遞至啟動的應用程式。iOS 版 Google 地圖應用程式支援下列網址配置：

• comgooglemaps:// 和 comgooglemaps-x-callback://：這些配置可讓您啟動 iOS 版 Google 地圖應用程式，並執行下列任一操作：

  • Display a map at a specified location and zoom level.
  • Search for locations or places, and display them on a map.
  • Request directions from one location to another. 路線可透過四種交通方式規劃：開車、步行、騎單車和大眾運輸。
  • 為應用程式新增導覽功能。
  • 在 iOS 8 中，使用 comgooglemaps-x-callback:// 在應用程式完成時發出回呼。回呼通常用於將使用者帶回原本開啟 iOS 版 Google 地圖的應用程式。請注意，在 iOS 9 上，系統會在狀態列左上角自動提供「返回」連結。

• comgooglemapsurl://：這個配置方案可讓您使用來自電腦版 Google 地圖網站的網址，啟動 iOS 版 Google 地圖應用程式。這表示您可以為使用者提供原生行動裝置體驗，而非單純載入 Google 地圖網站。

  • 原始網址可以是 maps.google.com、google.com/maps，或是使用任何有效的頂層國家/地區網域，而非 com。您也可以傳遞 goo.gl/maps 重新導向網址。
  • 您可以使用 x-source 和 x-success 參數搭配 comgooglemapsurl:// 網址架構，發出回呼。

啟動 iOS 版 Google 地圖應用程式並執行特定功能

如要啟動 iOS 版 Google 地圖應用程式，並視需要執行其中一個支援的功能，請使用下列格式的網址配置：

comgooglemaps://?parameters

或是：

comgooglemaps-x-callback://?parameters

本文後續會詳細說明參數。

檢查裝置上是否有 Google 地圖應用程式

在應用程式中向使用者顯示其中一個網址之前，請先確認已安裝應用程式。應用程式可以使用以下程式碼，檢查網址配置是否可用：

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)

[[UIApplication sharedApplication] canOpenURL:
    [NSURL URLWithString:@"comgooglemaps://"]];

舉例來說，如要顯示紐約中央公園的地圖，您可以使用下列程式碼：

if (UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)) {
  UIApplication.shared.openURL(URL(string:
    "comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic")!)
} else {
  print("Can't use comgooglemaps://");
}

if ([[UIApplication sharedApplication] canOpenURL:
     [NSURL URLWithString:@"comgooglemaps://"]]) {
  [[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic"]];
} else {
  NSLog(@"Can't use comgooglemaps://");
}

顯示地圖

使用網址配置，以指定的縮放等級和位置顯示地圖。You can also overlay other views on top of your map, or display Street View imagery.

參數

All of the following parameters are optional. 如果未設定參數，網址配置會啟動 Google 地圖 iOS 版應用程式。

• center：這是地圖檢視區中心點。格式為以半形逗號分隔的 latitude,longitude 字串。
• mapmode：設定要顯示的地圖類型。可設為：standard 或 streetview。如未指定，系統會使用目前的應用程式設定。
• views：開啟/關閉特定檢視畫面。可設為：satellite、traffic 或 transit。您可以使用半形逗號分隔符號設定多個值。如果指定的參數沒有值，則會清除所有檢視畫面。
• zoom：指定地圖的縮放等級。

以下範例網址會顯示以紐約為中心，縮放率為 14 的地圖，並開啟交通資訊檢視畫面：

comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic

以下列舉其他幾個例子：

comgooglemaps://?center=37.788463,-122.392545&zoom=12

comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

搜尋

Use this scheme to display search queries in a specified viewport location.

參數

除了用於顯示地圖的參數外，搜尋也支援 q 參數。

• q：搜尋的查詢字串。

以下是搜尋指定位置附近的「Pizza」的網址範例：

comgooglemaps://?q=Pizza&center=37.759748,-122.427135

以下列舉其他幾個例子：

comgooglemaps://?q=Steamers+Lane+Santa+Cruz,+CA&center=37.782652,-122.410126&views=satellite,traffic&zoom=15

comgooglemaps://?q=Google+Japan,+Minato,+Tokyo,+Japan&center=35.660888,139.73073&zoom=15&views=transit

顯示路線

使用這個配置，要求並顯示兩個地點之間的路線。You can also specify the transportation mode.

參數

• saddr：設定路線搜尋的起點。可以是經緯度、查詢格式化的地址，如果查詢字串傳回多個結果，系統會選取第一個結果。如果值留空，系統會使用使用者的目前位置。
• daddr：設定路線搜尋的終點。格式和行為與 saddr 相同。
• directionsmode：運送方式。可設為：driving、transit、bicycling 或 walking。

以下範例網址會顯示 Google NYC 和 JFK 機場之間的大眾運輸路線指引：

comgooglemaps://?saddr=Google+Inc,+8th+Avenue,+New+York,+NY&daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York&directionsmode=transit

以下列舉其他幾個例子：

comgooglemaps://?saddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA+94043&daddr=Google+Inc,+345+Spear+Street,+San+Francisco,+CA&center=37.422185,-122.083898&zoom=10

comgooglemaps://?saddr=2025+Garcia+Ave,+Mountain+View,+CA,+USA&daddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA,+United+States&center=37.423725,-122.0877&directionsmode=walking&zoom=17

指定回呼網址

如果您想指定回呼網址，必須使用 comgooglemaps-x-callback:// 網址通訊協定。此配置遵循 x-callback-url 規格。使用此配置方案呼叫 iOS 版 Google 地圖應用程式時，應用程式會在畫面頂端顯示按鈕。輕觸這個按鈕會向您指定的網址發出回呼。

對 comgooglemaps-x-callback:// 的請求必須符合以下格式：

comgooglemaps-x-callback://?parameters

參數

x-callback 網址配置接受與 comgooglemaps:// 網址配置相同的參數，並加上下列額外參數。這兩個參數皆為必填。

• x-source：傳送 x-callback 要求的應用程式名稱。建議使用簡稱。
• x-success：完成時要呼叫的網址。這通常是您自有應用程式的網址通訊協定，可讓使用者返回原始應用程式。

請注意，應用程式必須註冊自己的網址通訊協定，才能回應回呼網址。

1. 請確認應用程式已註冊可回應回呼要求的網址通訊協定。
2. 在 x-source 參數中傳遞回呼按鈕的標籤。
3. 在 x-success 參數中傳遞回呼網址。

以下範例會啟動 iOS 版 Google 地圖應用程式，並顯示以紐約為中心的地圖。應用程式也會顯示標示為「SourceApp」的按鈕。點選「SourceApp」按鈕時，iOS 版 Google 地圖應用程式會向虛構的網址通訊協定 sourceapp://?resume=true 發出回呼。

comgooglemaps-x-callback://?center=40.765819,-73.975866&zoom=14
   &x-success=sourceapp://?resume=true
   &x-source=SourceApp

如同 comgooglemaps:// 網址配置，您應先確認裝置上有可用的 iOS 版 Google 地圖應用程式，且支援 x-callback 網址配置。應用程式可以使用下列程式碼，檢查網址配置是否可用：

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemaps-x-callback://"]];

以下是讓使用者在搜尋甜點後返回應用程式的網址範例。

comgooglemaps-x-callback://?q=dessert&center=37.759748,-122.427135
   &x-success=sourceapp://?resume=true
   &x-source=Nom+Nom

在應用程式中加入導覽功能

您可以使用路線要求啟動 iOS 版 Google 地圖應用程式，讓使用者輕鬆透過應用程式存取行車路線導航功能。您可以使用 comgooglemaps:// 或 comgooglemaps-x-callback:// URI 配置。

這個程式碼片段說明如何使用 comgooglemaps-x-callback:// 配置要求路線，然後在使用者準備就緒時返回應用程式。程式碼會執行以下作業：

1. 確認 comgooglemaps-x-callback:// 網址架構可用。
2. 開啟 iOS 版 Google 地圖應用程式，然後要求導航至紐約市 JFK 機場。如要從使用者目前位置取得路線，請將起點地址留空。
3. 在 iOS 版 Google 地圖應用程式中新增「AirApp」按鈕。按鈕標籤是由 x-source 參數定義。
4. 使用者按下返回按鈕時，呼叫虛構的網址配置 sourceapp://。

let testURL = URL(string: "comgooglemaps-x-callback://")!
if UIApplication.shared.canOpenURL(testURL) {
  let directionsRequest = "comgooglemaps-x-callback://" +
    "?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
    "&x-success=sourceapp://?resume=true&x-source=AirApp"

  let directionsURL = URL(string: directionsRequest)!
  UIApplication.shared.openURL(directionsURL)
} else {
  NSLog("Can't use comgooglemaps-x-callback:// on this device.")
}

NSURL *testURL = [NSURL URLWithString:@"comgooglemaps-x-callback://"];
if ([[UIApplication sharedApplication] canOpenURL:testURL]) {
  NSString *directionsRequest = @"comgooglemaps-x-callback://" +
      @"?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
      @"&x-success=sourceapp://?resume=true&x-source=AirApp";
  NSURL *directionsURL = [NSURL URLWithString:directionsRequest];
  [[UIApplication sharedApplication] openURL:directionsURL];
} else {
  NSLog(@"Can't use comgooglemaps-x-callback:// on this device.");
}

透過 Google 地圖電腦版網址啟動 iOS 版 Google 地圖應用程式

如果您的應用程式可以存取現有的 Google 地圖網址 (例如網頁或資料庫中的網址)，您可以使用這個通訊協定，在 iOS 版 Google 地圖應用程式中開啟該網址，為使用者提供最佳的原生體驗。

1. 將 http:// 或 https:// 配置替換為 comgooglemapsurl://。
2. 如要使用回呼，請加入 x-source 和 x-success 參數。此配置遵循 x-callback-url 規格。

支援的 Google 地圖網址格式

comgooglemapsurl:// 配置支援符合此規則運算式的網址，其中 {TLD} 是指任何有效的頂層國家/地區網域。我們已加入換行符號，以便清楚呈現：

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

檢查 Google 地圖應用程式是否可用

請先確認裝置上有 iOS 版 Google 地圖應用程式，且支援網址架構：

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemapsurl://"]];

範例

一般 Google 地圖網址範例：

原始 Google 地圖網址：

https://www.google.com/maps/preview/@42.585444,13.007813,6z

使用網址配置：

comgooglemapsurl://www.google.com/maps/preview/@42.585444,13.007813,6z

一般 Google 地圖網址範例：

原始 Google 地圖網址：

https://maps.google.com/?q=@37.3161,-122.1836

使用網址配置：

comgooglemapsurl://maps.google.com/?q=@37.3161,-122.1836

使用 x-callback 要求前往東京鐵塔的路線示例：

原始 Google 地圖網址：

http://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1

以下範例會啟動 iOS 版 Google 地圖應用程式，並顯示地圖，其中包含前往東京鐵塔的路線，如原始 Google 地圖網址 (上方) 所述。應用程式也會顯示標示為「SourceApp」的按鈕。點選「SourceApp」按鈕時，iOS 版 Google 地圖應用程式會發出回呼至虛構的網址通訊協定 sourceapp://?resume=true。

comgooglemapsurl://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1
    &x-source=SourceApp
    &x-success=sourceapp://?resume=true