Google Maps API 開發指南

,
1

Google Maps Platform 簡介與準備工作

Google Maps Platform 提供了一系列強大的 API 和 SDK，讓開發者能夠將 Google Maps 的豐富地理空間數據和功能整合到自己的應用程式和網站中。從簡單的地圖嵌入到複雜的路線規劃、地點搜索和地理編碼，Google Maps Platform 為現代網頁開發提供了無限可能。

在開始之前，您需要確保具備以下條件：

  1. Google 帳戶：您需要一個有效的 Google 帳戶來存取 Google Cloud Console 並管理您的 API 金鑰。
  2. Google Cloud Platform (GCP) 專案：所有的 Google Maps Platform API 都需要透過 GCP 專案進行管理。
  3. 啟用帳單：雖然 Google Maps Platform 提供每月免費用量額度，但您仍需在 GCP 專案中設定有效的帳單帳戶才能使用這些 API。這是為了處理超出免費額度的使用量。請放心，除非您的使用量超過免費額度，否則不會產生費用。

建立 Google Cloud Platform 專案

若要開始使用 Google Maps Platform，第一步是在 Google Cloud Console 中建立或選取一個專案。

  1. 前往 Google Cloud Console。
  2. 如果您是首次使用，請同意服務條款。
  3. 點擊頁面頂端的專案下拉選單（可能顯示為「選取專案」或您目前的專案名稱）。
  4. 在跳出的視窗中，點擊「新增專案」。
  5. 輸入具描述性的專案名稱（例如：「我的地圖網站專案」）。
  6. 選擇或建立一個帳單帳戶，並確認與該專案連結。
  7. 選擇機構或位置（如果適用）。
  8. 點擊「建立」。系統需要一些時間來佈建您的新專案。

啟用所需的 Google Maps Platform API

專案建立完成後，您需要啟用您網站所需的特定 Google Maps Platform API。

  1. 確保您已選取剛剛建立的專案。
  2. 在左側導覽選單中，前往「API 和服務」>「程式庫」。
  3. 在 API 程式庫搜尋框中，輸入「Maps」。您會看到一系列與地圖相關的 API。
  4. 根據您的需求啟用 API。對於基本的網頁地圖顯示，您至少需要啟用 Maps JavaScript API。其他常用的 API 包括：
    • Geocoding API：用於將地址轉換為地理座標（緯度和經度），反之亦然。
    • Places API：提供地點詳細資訊、地點搜尋、自動完成等功能。
    • Directions API：計算兩點或多點之間的路線。
    • Distance Matrix API：計算多個起點和終點之間的行車時間和距離。
  5. 點擊您需要啟用的 API（例如，Maps JavaScript API）。
  6. 在 API 詳細頁面中，點擊「啟用」按鈕。
  7. 對您需要的所有其他 API 重複此啟用步驟。

產生 API 金鑰

啟用 API 後，您需要建立一個 API 金鑰。這個金鑰將作為您向 Google Maps Platform 發出請求時的憑證。

  1. 在左側導覽選單中，前往「API 和服務」>「憑證」。
  2. 在「憑證」頁面頂部，點擊「+ 建立憑證」。
  3. 從下拉選單中選擇「API 金鑰」。
  4. 系統會立即產生一個 API 金鑰。請務必妥善保管此金鑰，不要將其公開分享或嵌入到不安全的程式碼中。
  5. 您可以點擊金鑰右側的複製圖示，將其複製到剪貼簿。
  6. 建議立即點擊「編輯 API 金鑰」來設定限制，以提高安全性。

保護您的 API 金鑰：設定限制

保護您的 API 金鑰至關重要，以防止未經授權的使用，避免產生非預期的費用。我們強烈建議您為每個 API 金鑰 設定限制。

  1. 在「憑證」頁面，找到您剛剛建立的 API 金鑰，點擊其名稱或右側的編輯圖示。

  2. 在「編輯 API 金鑰」頁面，您可以設定以下限制：

    • 應用程式限制：這是最重要的安全措施。

      • HTTP 參照位址 (網站)：如果您只在特定網站上使用此金鑰，請選擇此選項。點擊「新增項目」，然後輸入您網站的網址（例如 *.yourdomain.com/* 或 yourdomain.com/*）。使用萬用字元 * 可以涵蓋子網域或特定路徑。這可以防止其他網站盜用您的金鑰。
      • IP 位址 (網路伺服器、cron 工作等)：如果金鑰僅用於伺服器端請求，您可以限制允許使用此金鑰的伺服器 IP 位址。
      • Android 應用程式 / iOS 應用程式：如果金鑰用於行動應用程式。

    • API 限制：為了進一步提高安全性，您可以指定此金鑰只能存取您已啟用的特定 API。

      • 選擇「限制金鑰」。
      • 在下拉選單中，勾選您希望此金鑰能夠存取的 API（例如，Maps JavaScript API, Geocoding API）。
      • 點擊「確定」。

  3. 完成設定後，點擊頁面底部的「儲存」按鈕。套用限制可能需要幾分鐘時間。

將 API 金鑰整合到您的網頁專案中

現在您已經擁有一個受保護的 API 金鑰，可以將其整合到您的 HTML 網頁中以載入 Google Maps JavaScript API。

基本方法是在您的 HTML 檔案 <head> 或 <body> 結尾處，加入以下 <script> 標籤：

<script async defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

請務必將 YOUR_API_KEY 替換為您實際產生的 API 金鑰。

  • async 屬性允許腳本非同步下載，不會阻塞頁面 HTML 的解析。
  • defer 屬性確保腳本在 HTML 文件完全解析後才執行。
  • key=YOUR_API_KEY：這是您驗證請求所必需的。
  • callback=initMap：這是必需的參數。它指定了在 Maps JavaScript API 完全載入後要執行的全域 JavaScript 函數的名稱（在此例中為 initMap）。您需要自行定義這個 initMap 函數。

實作基本地圖顯示

以下是一個簡單的 HTML 和 JavaScript 範例，展示如何在網頁上顯示一個基本地圖：

<!DOCTYPE html>
<html>
<head>
    <title>基本 Google 地圖範例</title>
    <style>
        /* 設定地圖容器的高度 */
        #map {
            height: 400px;
            width: 100%;
        }
    </style>
</head>
<body>
    <h3>我的第一張 Google 地圖</h3>
    <!-- 地圖將會顯示在這個 div 中 -->
    <div id="map"></div>

    <script>
        // 這個函數將在 Google Maps API 載入後被呼叫
        function initMap() {
            // 定義地圖中心點的緯度和經度
            const mapCenter = { lat: 25.034, lng: 121.565 }; // 例如：台北 101

            // 建立一個新的地圖實例，並將其附加到 id 為 'map' 的 HTML 元素上
            const map = new google.maps.Map(document.getElementById("map"), {
                zoom: 14, // 設定地圖的初始縮放級別
                center: mapCenter, // 設定地圖的中心點
            });

            // 您可以在這裡添加標記 (Marker) 或其他地圖元素
            const marker = new google.maps.Marker({
                position: mapCenter,
                map: map,
                title: '台北 101'
            });
        }
    </script>

    <!-- 異步載入 Google Maps JavaScript API，記得替換 YOUR_API_KEY -->
    <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
</body>
</html>

說明：

  1. HTML 部分包含一個 div 元素，其 id 為 map。這是地圖將要呈現的位置。
  2. CSS 用於設定 #map div 的高度，否則地圖將不可見。
  3. JavaScript 部分定義了 initMap 函數。
  4. 在 initMap 函數內部：
    • 我們定義了地圖的中心點 mapCenter（緯度和經度）。
    • 使用 new google.maps.Map() 建立了一個新的地圖對象，指定了要附加到的 HTML 元素 (document.getElementById("map")) 以及地圖選項（如縮放級別 zoom 和中心點 center）。
    • （可選）我們還添加了一個 google.maps.Marker 來在地圖中心放置一個標記。
  5. 最後的 <script> 標籤異步載入 Google Maps JavaScript API，並在載入完成後觸發 initMap 函數。

理解 Google Maps Platform 的計費方式

Google Maps Platform 採用按用量計費 (pay-as-you-go) 的模式。這意味著您只需為您實際使用的服務付費。

  • 每月免費額度：Google Maps Platform 為大多數 API 提供了每月 $200 美元的免費使用額度。對於許多中小型網站或開發測試來說，這個額度通常是足夠的。
  • 用量監控：您可以在 Google Cloud Console 的「Google Maps Platform」>「指標」部分監控您的 API 使用量。
  • 設定預算和提醒：為了避免意外費用，強烈建議您在 GCP 的「帳單」部分設定預算提醒。您可以設定當費用接近或達到某個閾值時收到通知。
  • 價格表：詳細的價格資訊可以在 Google Maps Platform 定價頁面 上找到。不同的 API（如動態地圖載入、地理編碼請求、地點搜尋請求）有不同的計費方式。

常見應用與進階功能

掌握了基本設定後，您可以探索 Google Maps Platform 的眾多功能來豐富您的網站：

  • 在地圖上新增多個標記 (Markers)：標示不同的興趣點。
  • 資訊視窗 (Info Windows)：點擊標記時顯示詳細資訊。
  • 自訂地圖樣式：使用 Styled Maps 或 Cloud-based Maps Styling 更改地圖的外觀（顏色、道路、標籤等）以符合您的品牌形象。
  • 繪製形狀：在地圖上繪製多邊形、線條、圓形。
  • 路徑規劃 (Directions Service)：顯示從 A 點到 B 點的路線。
  • 地點自動完成 (Places Autocomplete)：在用戶輸入地址或地點名稱時提供建議。
  • 地點搜尋 (Places Search)：尋找附近的餐廳、商店或其他興趣點。
  • 地理編碼與反向地理編碼 (Geocoding)：地址與座標之間的轉換。

疑難排解：常見問題

在設定過程中可能會遇到一些常見問題：

  • 地圖未顯示：
    • 檢查 API 金鑰是否正確且已添加到 <script> 標籤中。
    • 確認您已在 GCP 專案中啟用了所需的 API（特別是 Maps JavaScript API）。
    • 檢查瀏覽器開發人員控制台是否有任何錯誤訊息（例如，API 金鑰無效、帳單未啟用、參照位址限制錯誤等）。
    • 確保您的 API 金鑰限制（HTTP 參照位址）設定正確，包含了您網站的網址。
    • 確認包含地圖的 div 元素具有明確的高度。
  • ApiNotActivatedMapError：表示 Maps JavaScript API 尚未在您的專案中啟用。
  • RefererNotAllowedMapError：表示您的 API 金鑰設定了 HTTP 參照位址限制，但目前的網站網址不在允許列表中。
  • InvalidKeyMapError：表示您的 API 金鑰無效或格式錯誤。
  • 帳單相關錯誤：確保您的專案已連結到有效的帳單帳戶。

仔細檢查 Google Cloud Console 中的設定以及瀏覽器的錯誤訊息通常能幫助您快速定位並解決問題。

透過遵循這些詳細步驟，您將能夠成功地為您的網頁專案設定和整合 Google Maps API，從而提升使用者體驗並提供豐富的地理空間功能。

需要專業協助來整合 Google Maps Platform 或開發功能豐富的地理位置應用程式嗎？Tenten 的專家團隊擁有豐富的經驗，能夠協助您充分利用 Google Maps 的強大功能，為您的使用者打造無縫且引人入勝的體驗。無論是複雜的路線規劃、地點資料庫整合，還是自訂地圖視覺化，我們都能提供量身訂製的解決方案。立即聯繫我們，了解我們如何能協助您的專案更上一層樓。

預約免費諮詢會議