使用 Maps 網址或 Places API，將使用者導向 Google 地圖地點詳細資料和路線

在現今位置感知的世界中，使用者希望能順暢存取地點資訊、路線和導航功能。無論是透過訊息應用程式、當地情境探索應用程式、物流和交通平台、旅遊規劃工具或房地產資訊平台，使用者通常都需要快速查看位置詳細資料，或找到從 A 到 B 點的最佳路線。雖然開發人員可以自行建構應用程式內體驗，但善用 Google 地圖的全面性和熟悉介面，可提供更優質的體驗。

為了提供順暢的使用者體驗，Google 地圖網址必須具備完善的架構。不正確的網址會破壞這項體驗，將使用者導向錯誤位置、顯示一般地圖檢視畫面而非特定詳細資料，甚至導致連結失效。這會讓使用者感到挫折，無法達成目標。舉例來說，即使使用有效的 Google 地圖網址，使用者也可能會在預期查看特定商家詳細資料時，連到沒有相關資訊的一般地圖檢視畫面。請參考以下範例： 

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

這個地圖網址可用於開啟 Google 地圖，並根據經緯度顯示位置。但不會向使用者提供特定地點的詳細資料。

僅使用經緯度進行搜尋
僅使用經緯度進行搜尋

透過正確的網址，讓應用程式與 Google 地圖順暢連結

在 Google 地圖中開啟「地點詳細資料」頁面
含有專屬地點名稱的地圖網址會將使用者導向 Google 地圖上該地點的詳細資料頁面

Google 地圖平台 (GMP) 提供兩種主要方法來建構準確的網址：需要 API 金鑰的 Places API(新版)，以及免費且不需要金鑰的地圖網址。以下解決方案可解決不同的情境和用途：

GMP Places API(新版) 會傳回特定地點的完整資訊。要求 googleMapsUri 或 googleMapsLinks 欄位 (透過在欄位遮罩中指定) 時，API 回應會包含地點物件。這個物件包含預先格式化的網址，可用於在 Google 地圖中直接開啟對應的檢視畫面，例如地點詳細資料檢視畫面。

範例：

PlaceDetails 要求

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \
https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE

PlaceDetails 回應：

{
    "googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
    "googleMapsLinks": {
        "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
        "placeUri": "https://maps.google.com/?cid=3545450935484072529",
        "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
        "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
        "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
    }
}

上述範例中的 ChIJ3S-JXmauEmsRUcIaWtf4MzE 是雪梨歌劇院的 Place ID。地點 ID 是用來識別特定地點的文字 ID，可用於 Google 地點介面集資料庫和 Google 地圖。

免費擷取地點 ID

如要透過程式碼擷取地點 ID，您可以使用 Places API：Text Search(ID Only) 功能。這是取得地點 ID 的免費方法。進一步瞭解Place ID 和 Place API(新版) 要求。

Places API Text Search(ID Only) 要求：

curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Places API Text Search(ID Only) 回應：

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

使用者在地圖上點選或輕觸 POI 時，也可以擷取地點 ID。進一步瞭解可點選的 POI 圖示(JavaScript、Android、iOS)

導入作業

使用 Places API 時，開發人員只需從回應中擷取 googleMapsUri 或 googleMapsLinks 欄位，然後在 Google 地圖應用程式中啟動對應檢視畫面，或在未安裝應用程式的情況下，在瀏覽器中啟動對應檢視畫面。

功能 說明
directionsUri 連結至 Google 地圖，顯示從使用者目前位置到這個地點的路線
placeUri 連結至 Google 地圖，開啟這個地點的詳細資料頁面
writeAReviewUri 連結至 Google 地圖，開啟這個地點的評論撰寫頁面
reviewsUri 開啟 Google 地圖的連結，前往這個地點的評論頁面
photosUri 連結至 Google 地圖，開啟這個地點的相片頁面

請參閱開發人員指南，並立即試用這項功能。

使用 Google 地圖網址

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

可用的地圖動作如下：

  • 搜尋功能會啟動 Google 地圖應用程式，或在瀏覽器中 (如果未安裝應用程式) 顯示特定地點的圖釘，或是執行一般搜尋並啟動地圖來顯示結果。

  • 路線功能會啟動 Google 地圖應用程式，或在瀏覽器中顯示點間路線，或在行動裝置上的 Google 地圖中啟用即時路線導航功能 (如果未安裝應用程式)。

  • 街景服務全景功能可讓您啟動檢視器，以互動式全景顯示街景服務圖片。

請參閱 GMP Maps 網址開發人員說明文件，瞭解更多函式和範例。

以下將深入探討地圖網址的兩項重要功能：

  • 在 Google 地圖上顯示地點詳細資料：本節說明如何建構網址，以便在 Google 地圖上顯示特定地點的詳細資料。並詳細說明如何使用地點 ID 和精確查詢，處理名稱不唯一的地點。

  • 使用地圖網址提供路線：本節說明如何建立可提供地點間路線的網址，包括含有多個路線點的路線，以及逐轉導航。

在 Google 地圖上顯示地點詳細資料

Search 函式會使用兩個參數來完成地點搜尋，分別是 query(必要) 和 query_place_id(選用)。

所有搜尋要求都必須提供 query 參數。可接受地點名稱、以半形逗號分隔的經緯度座標，或一般搜尋字詞。

搜尋網址結構：

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

情境 1：顯示不重複地點名稱的地點詳細資料

https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
 在這個範例中，我們只指定地點名稱。這個網址會開啟雪梨歌劇院的詳細資料頁面。

在 Google 地圖中開啟「地點詳細資料」頁面
搜尋地點名稱和顯示地點詳細資料

請考慮名稱不唯一的地點。如果只使用這個不具唯一性的名稱進行搜尋，會發生什麼情況？請參閱下一個場景。

情境 2：搜尋地點時使用非唯一地點名稱 

https://www.google.com/maps/search/?api=1&query=7-Eleven

由於地點名稱不具唯一性，這個網址會在檢視區域中開啟附近 7-Eleven 地點的清單。使用者可以選擇特定商店查看詳細資料。

在 Google 地圖上開啟「地點清單」頁面
用於搜尋非專屬名稱的地點清單頁面

如要避免顯示位置清單，並直接存取特定詳細資料頁面，您可以使用更精確的方法。請參閱下一個範例。

情境 3：顯示非唯一地點名稱的地點詳細資料

當您處理常見的地點名稱時，簡單的名稱搜尋通常會傳回位置清單。如要直接連結至特定詳細資料頁面，可以使用下列任一方法：

方法 1：使用精確查詢，搭配地點名稱和地址 

https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia

在這個網址中，query 參數的格式為地點名稱、地址。這有助於縮小搜尋範圍，並直接連結至所需位置。

方法 2：使用 Place ID

地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。

https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM

其中 ChIJGcmcg7ZC1moRAOacd3HoEwM 是特定地點的專屬地點 ID。query 參數仍是必要參數，但只有在 Google 地圖找不到地點 ID 時才會使用。

情境 4：使用經緯度座標和地點 ID 顯示地點詳細資料

使用地點 ID 可確保 Google 地圖顯示詳細地點資訊。

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
使用經緯度和地點 ID 的地點詳細資料頁面
使用經緯度和地點 ID 的地點詳細資料頁面

免費擷取 Place ID

如要以程式輔助的方式擷取 Place ID，您可以使用 Places API：Text Search(僅限 ID) 功能。這是取得地點 ID的免費方法。進一步瞭解 Place ID 和 Place API(新版) 要求。

Places API Text Search(ID Only) 要求：

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Places API Text Search(ID Only) 回應：

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

使用者在地圖上點選或輕觸 POI 時，也可以擷取地點 ID。進一步瞭解可點選的 POI 圖示(JavaScript、Android、iOS)

結語

提供正確的地點詳細資料，是提供良好使用體驗的關鍵。為確保使用者前往正確的場地詳細資料頁面，請使用下列其中一種建議格式建立搜尋網址：

  • query=PLACE_NAME, ADDRESS
  • query=PLACE_NAME&query_place_id=PLACE_ID

如果您想顯示特定地點的詳細資料，請勿在 query 參數中只使用經緯度座標。query=latitude,longitude、query=PLACE_NAME,latitude,longitude 或 query=ADDRESS,latitude,longitude 等格式不會一律導向所需的地點詳細資料頁面。而是會顯示該位置的經緯度。

使用 Google 地圖網址進行分類搜尋

在分類搜尋中，您會傳送一般搜尋字詞，Google 地圖會嘗試在您指定位置附近尋找符合條件的產品資訊。如果未指定位置，Google 地圖會嘗試找出你目前所在位置附近的產品資訊。

情境 1：搜尋附近地點

https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
依類別搜尋 - 附近地點
類別搜尋 - 附近地點

使用 Google 地圖網址提供路線指引

路線功能會在地圖上顯示兩個或多個指定點之間的路徑，以及距離和行程時間。可讓開發人員進一步控管提供的路線。Google 媒體廣告平台的 Google 地圖網址指南說明文件提供詳細操作說明，協助您建構自訂指南的網址。

路線指引網址結構：

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

情境 1：尋找從使用者目前位置前往目的地的最佳路線

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

這個網址會開啟 Google 地圖，並顯示從使用者目前所在位置的駕車路線。

在這個網址中，origin 已省略。省略 origin 時，路徑會預設為最相關的起始位置，例如裝置位置 (如有)。如果沒有，產生的地圖會提供表單，讓使用者輸入來源。起點和目的地的值可以是地點名稱、地址，或以半形逗號分隔的緯度/經度座標。

travelmode 是選用參數。定義行程方式。這個參數可設定為：

  • 開車
  • 步行
  • 單車
  • 機車
  • 銀行代號

如果未指定 travelmode，Google 地圖會針對指定路線和/或使用者偏好顯示一或多個最相關的模式。

開發人員也可以使用 origin_place_id 參數和 destination_place_id 指定地點 ID。使用地點 ID 是確保連結至正確位置的最佳保證。

免費擷取 Place ID

如要以程式輔助的方式擷取 Place ID，您可以使用 Places API：Text Search(僅限 ID) 功能。這是取得地點 ID的免費方法。進一步瞭解 Place ID 和 Place API(新版) 要求。

Places API Text Search(ID Only) 要求：

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Places API Text Search(ID Only) 回應：

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

使用者在地圖上點選或輕觸 POI 時，也可以擷取地點 ID。進一步瞭解可點選的 POI 圖示(JavaScript、Android、iOS)

從使用者目前位置規劃路線
從使用者目前位置的路線

情境 3：提供即時路線導航服務

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

如果使用者目前位置(裝置位置) 可用且用作起點 (明確提供或在省略起點參數時隱含使用)，在網址中設定 dir_action=navigate 會以即時路線導航模式啟動 Google 地圖。否則會顯示路線預覽畫面。

當設定了 dir_action=navigate 且：

  • 指定的來源與使用者目前位置相近
  • 系統會略過來源，並提供使用者的目前位置

路線預覽畫面會在下列情況下啟動：

  • 未設定 dir_action=navigate
  • dir_action=navigate 已設好，且來源已指定，但來源與使用者的目前位置相距甚遠
  • dir_action=navigate 已設定，但來源遭到省略，且無法取得使用者的目前位置

請注意，導航功能不適用於所有 Google 地圖產品 (例如 Google 地圖網頁版)，且/或不適用於所有目的地。在這種情況下，系統會忽略這個參數。

即時路線導航 路線預覽
即時路線導航
路線預覽

結語

正確建構 Maps 網址，可確保使用者能快速且有效率地取得所需的正確資訊。

  • 請一律指定目的地，並盡可能使用 Place ID，確保準確度

  • 如果目標是提供即時導航，請加入 dir_action=navigate 參數，觸發即時路線導航功能。如果裝置位置可用且用於做為起點 (明確設定或省略)，導航會從使用者的目前位置開始

為應用程式選擇合適的方法

您有兩個主要選項：利用 Places API 提供的預先格式化網址，或在應用程式中手動建構 Google 地圖網址。每種方法都各有優缺點。

Places API：

  • 地點詳細資料回應中的 googleMapsUri 和 googleMapsLinks 欄位會提供可立即使用的網址，這麼做可縮短開發時間，並盡可能降低網址格式錯誤的風險。

  • 無法完全控管路線設定。googleMapsLinks 雖然提供基本路線，但不支援路線控點或進階自訂功能。此外，直接觸發即時路線導航功能也相對不直觀。

地圖網址：

  • 提供更大的彈性和控管權限。開發人員可以建構網址來顯示地點詳細資料，並設定路線的各種面向，包括新增路線點、指定行程模式，以及啟動即時路線導航。

  • 需要對網址參數和結構有更深入的瞭解。如果不小心進行手動建構，就會增加發生錯誤的可能性。

使用 Urchin 流量監視器 (UTM) 參數改善地圖網址

為了協助 Google 進一步瞭解開發人員如何整合 Google 地圖網址，並確保最佳成效，我們建議您在網址結構中加入 Urchin 流量監視器 (UTM) 追蹤參數。加入 utm_source 和 utm_campaign 參數，即可提供寶貴的資料，協助我們分析使用模式並改善 Google 地圖網址產品。

針對 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=YourAppName&utm_campaign=place_details_search

持續使用這些參數有助於我們找出可改善的部分，更有效地排除問題，並最終為所有使用者提供更優質的體驗。

後續步驟

建議參閱以下文章：

貢獻者

主要作者：

Teresa Qin | Google 地圖平台解決方案工程師