Google 地圖網址架構 (iOS)

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

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

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

注意： 地圖網址可讓您建立通用的跨平台網址，用於啟動 Google 地圖並執行搜尋、規劃路線、顯示地圖檢視畫面和全景圖片。建議您使用跨平台的 地圖網址啟動 Google 地圖，因為這些通用網址可處理更多地圖要求，並支援各種使用者平台。您應僅將 iOS 專屬的 Google 地圖網址結構用於行動平台上可能無法運作的功能 (例如即時路線導航)。

通用連結和 Google 地圖

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

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

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

例如：

Swift

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

Objective-C

[[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 9 開始，應用程式必須宣告要開啟的網址配置。詳情請參閱「入門指南」。

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

comgooglemaps://?parameters

或是：

comgooglemaps-x-callback://?parameters

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

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

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

Swift

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

Objective-C

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

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

Swift

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://");
}

Objective-C

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 網址配置。應用程式可以使用下列程式碼，檢查網址配置是否可用：

Swift

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

Objective-C

[[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:// 網址配置。

注意： 透過 x-source 參數新增的按鈕不會顯示在即時路線導航 UI 中。

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

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

Swift

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.")
}

Objective-C

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 地圖應用程式，且支援網址架構：

Swift

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

Objective-C

[[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