如何為你的應用程式加入地圖：嵌入式地圖、互動地圖與門市查詢

要為應用程式加入地圖，首先要決定你需要的是靜態嵌入（一個地點加上一個標記，例如「找到我們的店」），還是互動式地圖（根據你的資料顯示許多標記、篩選、群集，以及「附近」功能）。如果只有一個地點，嵌入式地圖最快，而且使用 Google 的 Maps Embed API 是免費的。對於互動式地圖，請使用 JavaScript 地圖函式庫（Google Maps JavaScript API、Mapbox GL JS，或開源的 Leaflet 搭配圖磚供應商），把每個地點的緯度與經度存到你的資料庫中，並把你的 API 金鑰限制在你自己的網域。以下各供應商的細節，都以 2026 年 9 月各家官方文件為準。

你需要哪一種地圖？

大多數小型商業網站只需要第一列的做法。目錄、市集與清單網站則需要第三與第四列的功能。

你的選項

Google Maps Platform

Google 的入門指南表示，你必須建立一個已啟用計費的 Cloud 專案，並啟用你想使用的 API。其隨用隨付定價對 Essentials SKU（包括動態地圖）提供每月 10,000 次事件的免費上限，超過後動態地圖的費用為每 1,000 次事件 7.00 美元（以第一個用量級距計）。Maps Embed 這一項則列為不限量且免費。Google 也提供每月訂閱方案。目前的數字請查看 Google Maps Platform 定價。

Mapbox

Mapbox 的定價頁面列出，Mapbox GL JS 在網頁上每月有 50,000 次免費地圖載入，之後每 1,000 次 5.00 美元。請參閱 Mapbox 定價。

Leaflet 與 OpenStreetMap

Leaflet 自我描述為用於行動裝置友善互動式地圖的開源 JavaScript 函式庫，約 42 KB 的 JavaScript。它需要從某處取得地圖圖磚（也就是地圖的圖片）。OpenStreetMap 的公開圖磚伺服器很有吸引力，但其圖磚使用政策要求顯示出處標示、禁止大量下載、不提供服務保證，並警告商業服務存取權限可能會被撤回。若是正式的產品，請使用可與 Leaflet 搭配的商業或自行架設的圖磚來源。

API 金鑰：公開，但要加以限制

瀏覽器中使用的地圖金鑰，任何打開你頁面的人都看得到。這是預期中的情況，但也代表有人可能複製你的金鑰，耗用你的額度，讓你的帳單暴增。Google 的安全指引是新增網站（HTTP 參照來源）限制，列出你的網域；並新增API 限制，讓金鑰只能用於你實際使用的 API。

用於伺服器端服務的金鑰，例如要對數千個地址做地理編碼，應該是另外的金鑰，並保存在伺服器端機密中，不要放在頁面上。也請在供應商的主控台設定預算警示或配額，確保一次失誤不會變成一筆大額帳單。

地理編碼：把地址轉成座標，只做一次

地圖繪製的是緯度與經度，而不是地址。把地址轉換成座標的過程稱為地理編碼，大多數供應商會依請求次數收費。有效率的做法是：

1. 當地點資料被儲存時，在伺服器上對其地址進行地理編碼。
2. 把緯度與經度存到資料庫中。
3. 地圖讀取已儲存的座標，絕不在頁面瀏覽時進行地理編碼。

請查閱各供應商的條款，了解你可以保存地理編碼結果多久；各家的規定不同。

提示詞範例

單一的嵌入式地圖：

在「聯絡我們」頁面，使用 Maps Embed API 嵌入一張 Google 地圖，顯示我們的地址（12 High Street, Leeds），金鑰存放在 GOOGLE_MAPS_EMBED_KEY 中。在地圖下方加上「取得路線」連結。在手機上讓它全寬顯示，並採用延遲載入。

地點列表的互動式地圖：

在 listings 資料表中新增緯度與經度欄位。當刊登建立或地址變更時，在伺服器上使用存放在 GEOCODING_API_KEY 中的金鑰對其進行地理編碼，並儲存座標。在「瀏覽」頁面上，使用 Leaflet 顯示地圖，每筆刊登一個標記；當標記重疊時使用群集。點擊標記時顯示標題、價格與連結。地圖與清單應使用相同的篩選條件。

「附近」功能：

新增一個「附近」按鈕，詢問訪客的位置，並顯示 10 公里內的刊登，依距離排序。如果對方拒絕提供位置權限，讓他們改為輸入城市。

逐步操作

1. 從上方的表格選擇地圖類型。
2. 建立供應商帳號與專案，只啟用你需要的 API。
3. 建立金鑰：一把限制在你網域（建置期間包括預覽網域）的瀏覽器金鑰，以及（如有需要）一把地理編碼用的伺服器金鑰。
4. 把金鑰存成機密，並要求你的建置工具使用它們；即使瀏覽器金鑰最後會出現在頁面中，它仍然受到限制。
5. 為每個地點儲存座標到資料庫中。
6. 建置地圖：標記、彈出視窗、群集，以及合理的預設縮放層級。
7. 搭配一份清單。 單獨的地圖在手機上和對螢幕閱讀器的使用者來說都很難用。請以清單顯示相同的結果。
8. 在供應商主控台設定預算警示。
9. 發布並在正式網域上測試，因為參照來源限制經常會讓地圖在加入正式網域之前無法顯示。

常見錯誤

• 金鑰沒有限制。 任何人都可以在他們自己的網站上重複使用。
• 每次頁面瀏覽都做地理編碼。 既慢又貴；應在儲存時做一次。
• 忘記在金鑰限制中加入正式網域。 在預覽中能運作，但在正式環境中變成空白的灰色方塊。
• 只有地圖、沒有清單的版面。 只有標記而沒有清單，在小螢幕上很難用，對螢幕閱讀器也不易存取。
• 數百個標記卻沒有群集。 難以閱讀，而且很慢。
• 缺少出處標示。 大多數地圖與圖磚供應商都要求顯示出處，隱藏它會違反其條款。
• 頁面載入時就要求定位。 只有在使用者點擊「附近」時才要求。

檢查清單

• 已為工作選擇正確的地圖類型
• 瀏覽器金鑰已限制在你的網域與所需的 API
• 伺服器端金鑰保存在機密中
• 座標已儲存在資料庫中，且只做一次地理編碼
• 結果也以清單的形式顯示
• 標記很多時使用群集
• 出處標示清楚可見
• 已在供應商處設定預算警示
• 已在正式網域與手機上測試

在 Mythex 中加入地圖

Mythex 沒有內建的地圖整合；你需要自行帶入供應商的金鑰，把它存成專案機密（或在代理程式顯示機密卡片時貼上），然後在對話中要求加入地圖，做法如整合任何 API所述。座標存放在專案的資料庫中。記得把你的預覽網域與已發布網域都加入金鑰的網站限制中，並在變更機密後重新發布。

地圖通常會搭配搜尋與列表一起使用：請參閱如何為應用程式加入搜尋、如何建置目錄網站，以及如何建置小型商業網站。

常見問題