在現今這個位置資訊無所不在的世界，使用者希望能夠順暢地存取地點資訊、路線和導航功能。無論是透過即時通訊應用程式、本地情境探索應用程式、物流和運輸平台、旅遊規劃工具或房地產資訊平台，使用者通常都需要快速查看地點詳細資料，或是找出從 A 地到 B 地的最佳路線。開發人員可以自行建構應用程式內體驗，但利用 Google 地圖全面且熟悉的介面，可提供更優質的體驗。
如要提供流暢的使用者體驗，請務必使用結構良好的 Google 地圖網址。如果網址有誤，使用者體驗就會受到影響，例如導向錯誤的地點、顯示一般地圖檢視畫面而非特定詳細資料，甚至導致連結失效。這會讓使用者感到沮喪，無法達成目標。舉例來說，即使地圖網址有效，使用者想查看特定商家的詳細資料時，可能只會看到一般地圖檢視畫面，沒有任何相關資訊。請參閱以下範例：
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
這個地圖網址可開啟 Google 地圖，並根據經緯度顯示位置。但不會提供特定地點的詳細資訊。
透過準確的網址，在應用程式與 Google 地圖之間建立無縫連結
Google 地圖平台 (GMP) 提供兩種主要方法，可建構準確的網址：Places API (新版) (需要 API 金鑰) 和地圖網址 (免費且不需要金鑰)。下列解決方案適用於不同情境和用途：
使用 Google 地圖平台 Places API(新版) 的 googleMapsUri 或 googleMapsLinks 欄位
GMP Places API(新版) 會傳回特定地點的完整資訊。要求 googleMapsUri 或 googleMapsLinks 欄位時 (在欄位遮罩中指定)，API 回應會包含地點物件。這個物件包含預先格式化的網址，可用於直接在 Google 地圖中開啟對應的檢視畫面，例如地點詳細資料檢視畫面。
範例：
Place Details 要求
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
Place Details 回應：
{
"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 是雪梨歌劇院的地點 ID。地點 ID 是文字 ID，可唯一識別 Google 地方資訊資料庫和 Google 地圖中的地點。
免付費擷取地點 ID
如要以程式輔助方式擷取地點 ID，可以使用 Places API：Text Search(ID Only) 功能。這是取得地點 ID 的零成本方法。進一步瞭解地點 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"
}
]
}使用者點選或輕觸地圖上的搜尋點時，也可以擷取地點 ID。 進一步瞭解可點選的興趣點圖示(JavaScript、Android、iOS)
導入作業
使用 Places API 時，開發人員只要從回應中擷取 googleMapsUri 或 googleMapsLinks 欄位，即可啟動 Google 地圖應用程式中的對應檢視畫面，或在未安裝應用程式時啟動瀏覽器。
| 功能 | 說明 |
|---|---|
| directionsUri | 連結：開啟 Google 地圖，顯示從使用者目前位置到這個地點的路線 |
| placeUri | 開啟 Google 地圖，前往這個地點的詳細資料頁面 |
| writeAReviewUri | 連結：開啟 Google 地圖，前往這個地點的評論撰寫頁面 |
| reviewsUri | 連結：開啟 Google 地圖，前往這個地點的評論頁面 |
| photosUri | 連結：開啟 Google 地圖，前往這個地點的相片頁面 |
請參閱開發人員指南，立即試用這項功能。
使用地圖網址
使用地圖網址，您就可以建立通用的跨平台網址來啟動 Google 地圖並執行搜尋、規劃路線與導航，以及顯示地圖檢視和全景圖片。無論使用哪個平台，網址語法都相同。使用地圖網址時，不需要 Google API 金鑰。
可執行的地圖動作包括：
搜尋功能會啟動 Google 地圖應用程式 (如果未安裝應用程式，則會啟動瀏覽器)，顯示特定地點的圖釘，或執行一般搜尋並啟動地圖來顯示結果。
路線規劃功能會啟動 Google 地圖應用程式 (如果未安裝，則會啟動瀏覽器)，顯示兩點之間的路線，或在行動裝置上啟用 Google 地圖的即時路線導航。
街景服務全景函式可啟動檢視器，以互動式全景形式顯示街景服務圖片。
如要瞭解更多函式和範例，請參閱 GMP 地圖網址開發人員說明文件。
以下將深入探討地圖網址的兩項主要功能：
在 Google 地圖上顯示地點詳細資料：本節說明如何建構網址，在 Google 地圖上顯示特定地點的詳細資料。此外，本文也詳細說明如何使用地點 ID 和精確查詢，處理名稱重複的地點。
使用地圖網址提供路線：本節說明如何建立網址，提供地點之間的路線，包括有多個中途點的路線和逐步導航。
在 Google 地圖上顯示地點詳細資料
Search 函式會採用兩個參數來完成地點搜尋，分別是 query(必要) 和 query_place_id(選用)。
所有搜尋要求都必須提供 query 參數。這項服務接受地點名稱、以半形逗號分隔的經緯度座標，或一般搜尋字詞。
搜尋網址結構：
https://www.google.com/maps/search/?api=1¶meters
情境 1：顯示特定地點名稱的地點詳細資料
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
現在，請考慮名稱不獨特的地點。如果只用這個非專屬名稱搜尋，會發生什麼事？請參閱下一個情境。
情境 2：搜尋地點時，地點名稱並非獨一無二
https://www.google.com/maps/search/?api=1&query=7-Eleven
由於地點名稱不具唯一性，這個網址會開啟視埠內附近 7-Eleven 地點的清單。使用者可以選擇特定商店，查看詳細資料。
如要避免顯示位置清單，並直接存取特定詳細資料頁面，可以使用更精確的方法。請參閱下一個範例。
情境 3：顯示非唯一地點名稱的地點詳細資料
處理常見地名時，簡單的名稱搜尋通常會傳回地點清單。如要直接連結至特定詳細資料頁面，請使用下列其中一種方法：
方法 1：使用精確查詢 (地點名稱和地址)
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
在這個網址中，query 參數的格式為地點名稱、地址。這有助於縮小搜尋範圍，並直接連結至預期地點。
方法 2：使用地點 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，可以使用 Places API：Text Search(僅限 ID) 功能。這是取得地點 ID 的零成本方法。進一步瞭解地點 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"
}
]
}使用者點選或輕觸地圖上的搜尋點時，也可以擷取地點 ID。 進一步瞭解可點選的興趣點圖示(JavaScript、Android、iOS)
結語
提供準確的地點詳細資料是獲得良好體驗的關鍵。為確保使用者前往正確的詳細資料頁面，請使用下列任一建議格式建構搜尋網址：
query=PLACE_NAME, ADDRESSquery=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 地圖網址路線指引說明文件提供詳細操作說明， 教您如何建構自訂路線指引的網址。
路線網址結構：
https://www.google.com/maps/dir/?api=1¶meters
情境 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 最能確保連結至正確地點。
免費擷取地點 ID
如要以程式輔助方式擷取地點 ID，可以使用 Places API：Text Search(僅限 ID) 功能。這是取得地點 ID 的零成本方法。進一步瞭解地點 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"
}
]
}使用者點選或輕觸地圖上的搜尋點時，也可以擷取地點 ID。 進一步瞭解可點選的興趣點圖示(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 地圖網頁版) 不支援導航功能，且導航功能不適用於所有目的地。在這些情況下，系統會忽略這個參數。
 |
 |
結語
只要正確建構 Google 地圖網址，就能確保使用者快速有效率地取得所需資訊。
請務必指定目的地，並盡可能使用地點 ID，確保準確度
如要立即提供導航功能，請加入 dir_action=navigate 參數，觸發即時路線導航。如果裝置位置可用且做為起點 (明確設定或省略)，系統會從使用者目前位置開始導航
為應用程式選擇合適的方法
您有兩種主要選擇：使用 Places API 提供的預先格式化網址，或在應用程式中手動建構 Google 地圖網址。每個方法都各有優缺點。
Places API：
地點詳細資料回應中的
googleMapsUri和googleMapsLinks欄位提供可直接使用的網址，可縮短開發時間，並降低網址格式錯誤的風險。對路線設定的控制權較少。
googleMapsLinks雖然提供基本路線，但不支援路線控點或進階自訂功能。此外，直接觸發逐向導航的程序也相對複雜。
地圖網址：
提供更大的彈性和控制權。開發人員可以建構網址來顯示地點詳細資料，並設定各種路線資訊，包括新增途經點、指定交通方式，以及啟動逐向導航。
您必須深入瞭解網址參數和結構，如果沒有仔細手動建構，可能會發生錯誤。
改善含有 Urchin 流量監視器 (UTM) 參數的地圖網址
為協助 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 地圖平台解決方案工程師