Google 地圖 URL 配置

您可以使用 Google 地圖 URL 配置來啟動適用於 iOS 的「Google 地圖」應用程式，並執行搜尋、取得路線要求與顯示地圖檢視等功能。

當您啟動「Google 地圖」時，您的套件組合識別碼將會做為要求的一部分自動傳送出去。

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

總覽

URL 配置可讓您從另一個 iOS 應用程式或 Web 應用程式啟動原生 iOS 應用程式。 您可以在 URL 中設定要傳遞到已啟動應用程式的選項。 適用於 iOS 的「Google 地圖」應用程式支援下列 URL 配置：

• comgooglemaps:// 與 comgooglemaps-x-callback:// - 這些配置能讓您啟動適用於 iOS 的「Google 地圖」應用程式，並執行下列其中一個動作：

  • 以指定位置與縮放層級顯示地圖。
  • 搜尋位置或地點，並在地圖上顯示它們。

  • 要求兩個位置之間的路線。 系統能以四種運輸模式傳回路線：開車、步行、單車與大眾運輸。

  • 新增瀏覽至您的應用程式。

  • 透過　iOS 8，使用 comgooglemaps-x-callback:// 於應用程式完成時發出回呼。 回呼通常用來讓使用者返回原本開啟 Google Maps for iOS 的應用程式。 請注意，在 iOS 9 上，系統會在狀態列左側自動提供 [Back to] 連結。

• comgooglemapsurl:// - 此配置能讓您使用衍生自桌面「Google 地圖」網站之 URL 啟動適用於 iOS 的「Google 地圖」應用程式。 這表示您可以為使用者提供原生行動裝置體驗，而不是單純地載入「Google 地圖」網站。

  • 原始 URL 可以是針對 maps.google.com 或 google.com/maps 的 URL，或是使用任何有效頂層國家/地區網域（而非 com）。 您也可以傳遞 goo.gl/maps 重新導向 URL。
  • 您可以透過 comgooglemapsurl:// URL 配置，使用 x-source 與 x-success 參數發出回呼。

啟動適用於 iOS 的「Google 地圖」應用程式並執行特定功能

注意：從 iOS 9 開始，您的應用程式必須宣告它將開啟的網配置。 如需詳細資訊，請參閱開始使用。

如果要啟動適用於 iOS 的「Google 地圖」應用程式，並選擇性地執行其中一個支援的功能，請使用下列形式的 URL 配置：

comgooglemaps://?parameters

或：

comgooglemaps-x-callback://?parameters

本文件稍後將詳述參數。

檢查裝置上「Google 地圖」應用程式的可用性

在您於應用程式中將下列其中一個 URL 提供給使用者之前，您應該先驗證該應用程式是否已安裝。 您的應用程式可以使用下列程式碼來檢查 URL 配置是否可用：

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

顯示地圖

使用 URL 配置以使用指定縮放層級與位置來顯示地圖。 您也可以將其他檢視以疊加層的形式放在地圖上方，或是顯示「街景服務」影像。

參數

下列所有參數都是選擇性。 如果沒有設定任何參數，URL 配置只會啟動適用於 iOS 的「Google 地圖」應用程式。

• center：這是地圖檢視點的中心點。 格式為以逗點分隔的 latitude,longitude 字串。

• mapmode：設定顯示的地圖類型。 可以設定為：standard 或 streetview。 如果沒有指定，則將會使用目前的應用程式設定。

• views：開啟/關閉特定檢視。 可以設定為：satellite、traffic 或 transit。 可以使用逗點分隔符號來設定多個值。 如果只指定參數而未指定值，則會清除所有檢視。

• zoom：指定地圖的縮放層級。

下列範例 URL 將會顯示置中於紐約市、縮放層級為 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

搜尋

使用此配置來顯示位於所指定檢視點位置的搜尋查詢。

參數

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

• q：搜尋的查詢字串。

下列範例 URL 為針對指定位置搜尋「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

顯示路線

使用此配置以要求並顯示兩個位置之間的路線。 您也可以指定運輸模式。

參數

• saddr：設定路線搜尋的的起點。 這可以是「緯度,經度」，或是查詢格式的地址。 如果它是傳回多個結果的查詢字串，則會選擇第一個結果。 如果值是空白，則會使用使用者的目前位置。

• daddr：設定路線搜尋的終點。 具有與 saddr 相同的格式與行為。

• directionsmode：運輸方法。 可以設定為：driving、transit、bicycling 或 walking。

下列範例 URL 可顯示 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

指定回呼 URL

如果要指定回呼 URL，您必須使用 comgooglemaps-x-callback:// 網址配置。 此配置遵守 [x-callback-url 規格]。 當您以此配置呼叫適用於 iOS 的「Google 地圖」應用程式時，該應用程式將會在螢幕上方顯示一個按鈕。

點選此按鈕將會對您所指定的 URL 發出回呼。

針對 comgooglemaps-x-callback:// 的要求應為如下格式：

comgooglemaps-x-callback://?parameters

參數

X-callback URL 配置接受與 comgooglemaps:// URL 配置相同的參數，以及下列額外參數。 兩個參數都是必要參數。

• x-source：傳送 x-callback 要求的應用程式名稱。 建議使用簡短名稱。
• x-success：完成時要呼叫的 URL。 這通常會是您自己的應用程式的 URL 配置，允許使用者返回原始應用程式。

請注意，您的應用程式必須註冊它的 URL 配置，才能針對回呼 URL 做出回應。

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:// URL 配置相同，您應該先驗證適用於 iOS 的「Google 地圖」應用程式在該裝置上是否可用，以及是否支援 x-callback URL 配置。

您的應用程式可以使用下列程式碼來檢查 URL 配置是否可用：

Swift

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

Objective-C

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

下列 URL 範例能讓使用者在搜尋完 "dessert" 之後返回應用程式。

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:// URL 配置。

注意：透過 x-source 參數新增的按鈕，將不會顯示於轉向建議導航 UI 中。

下列程式碼片段顯示如何使用 comgooglemaps-x-callback:// 配置來要求路線，並在使用者準備好後返回您的應用程式。 程式碼將會執行下列動作：

1. 驗證 comgooglemaps-x-callback:// 網址配置是否可用。

2. 啟動適用於 iOS 的「Google 地圖」應用程式，並要求前往紐約市 JFK 機場的路線。 將起始地址保持空白，以從使用者的目前位置要求路線。

3. 將具有 [AirApp] 標籤的按鈕新增至適用於 iOS 的「Google 地圖」應用程式。 按鈕標籤是由 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 Maps 桌面 URL 啟動適用於 iOS 的「Google 地圖」應用程式

如果您的應用程式能夠存取現有的 Google Maps URL（例如在網頁上或資料庫內），您可以使用下面的配置來在適用於 iOS 的「Google 地圖」應用程式中開啟該 URL，以提供使用者最佳的原生體驗。

1. 以 comgooglemapsurl:// 取代 http:// 或 https://。
2. 如果要使用回呼，請包含 x-source 與 x-success 參數。 此配置遵守 [x-callback-url 規格]。

支援的 Google 地圖 URL 格式

comgooglemapsurl:// 配置支援符合下列規則運算式的 URL，其中 {TLD} 參照任何有效的頂層國家/地區網域。

為了更加清楚而加入斷行：

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

檢查「Google 地圖」應用程式的可用性

首先，請驗證適用於 iOS 的「Google 地圖」應用程式於該裝置上是否可用，以及是否支援 URL 配置：

Swift

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

Objective-C

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

範例

一般 Google 地圖 URL 範例：

原始 Google 地圖 URL：

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

使用 URL 配置：

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

一般 Google 地圖 URL 範例：

原始 Google 地圖 URL：

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

使用 URL 配置：

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

透過 x-callback 要求前往東京鐵塔之路線的範例：

原始 Google 地圖 URL：

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 地圖 URL（上方）所指定。

應用程式也會顯示具有 "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