Google Maps JavaScript API 入門使用教學與範例

這裡透過簡單的 Hello, World 範例，介紹 Google Maps JavaScript API 的基本使用方式。

Google Maps JavaScript API 是設計給網頁開發者所使使用的開發工具，您可以使用這個 API 將 Google 地圖安插在自己的網頁中，並且將自己的資料放在地圖上面呈現。

以下是 Google Maps JavaScript API 的 Hello, World 入門使用教學。

取得 API 金鑰

只要是需要使用到 Google 地圖 API 的應用程式，都會需要一個 API 金鑰，如果您沒有申請過 API 金鑰，請參考從 Google Developers Console 取得開發者用的 API 金鑰。

這個 API 金鑰除了可以讓應用程式使用 Google API 所提供的服務之外，也是紀錄使用量的依據，每一個應用程式專案有一定的配額限制，若是使用量太大以致於超出配額，就必須要付費另外購買配額。

Hello, World

這是一段 Google 地圖 API 的 Hello, World 程式碼：

<!DOCTYPE html>1
<html>
  <head>
    <style type="text/css">
      html, body, #map-canvas { height: 100%; margin: 0; padding: 0;}
    </style>
    <script type="text/javascript"
      src="https://maps.googleapis.com/maps/api/js?key=API_KEY">
    </script>2
    <script type="text/javascript">
      function initialize() {
        var mapOptions = {
          center: { lat: -34.397, lng: 150.644},
          zoom: 8
        };4
        var map = new google.maps.Map(
            document.getElementById('map-canvas'),
            mapOptions);5
      }
      google.maps.event.addDomListener(
          window, 'load', initialize);6
    </script>
  </head>
  <body>
<div id="map-canvas"></div>3
  </body>
</html>

這段程式碼主要的重點如下：

1 宣告這是一個 HTML5 的網頁應用程式。

2 引入 Google Maps API。

3 使用一個 <div> 放置地圖。

4 建立一個 JavaScript 變數，存放地圖相關的參數。

5 建立一個地圖物件，指定要顯示地圖的 <div> 與相關參數。

6 使用 event listener 讓地圖在網頁載入完成後再載入。

以下是各個重點說明。

宣告 HTML5 網頁應用程式

這裡在一開始加入的

<!DOCTYPE html>

是用來宣告這個網頁是屬於最新的 HTML5 格式，這樣可以確保瀏覽器使用標準模式（standards mode）來處理這個網頁，若是沒有加上這一行，或是無法解析這一行的瀏覽器，就以怪癖模式（quirks mode）來顯示網頁，這會造成一些 CSS 無法正常運作。

而有一些在怪癖模式中可以正常顯示的 CSS，反而在正常模式中會有問題，例如所有的以百分比為基礎的大小，都必需繼承自其父元素，如果其父元素中有任何一個無法判定大小，那麼該元素的大小就會變成 0 x 0 像素，為了解決這個問題，所以我們加入了這段 CSS 程式碼：

<style type="text/css">
  html { height: 100% }
  body { height: 100%; margin: 0; padding: 0 }
  #map-canvas { height: 100% }
</style>

這裡指定 map-canvas 這個 <div> 的高度為 100%，這裡要注意 <body> 與 <html> 的高度也要明確指定，不可省略。

引入 Google Maps API

在引入 Google Maps API 時，必需傳入自己的 API 金鑰，實際使用時要把上面的 API_KEY 替換為自己的金鑰，就像這樣：

<script type="text/javascript"
  src="https://maps.googleapis.com/maps/api/js?key=AIzaSyAUOrXGoWf6bt5U4qgfvtFIiz-_Hp_Oc4s">
</script>

Google 地圖所有的 API 都可以透過 https 加密連線的方式引入，如果您有需要一般的 http 協定，也可以使用 http://maps.googleapis.com/，而若是中國大陸的使用者，則必須改為 http://maps.google.cn/。

在引入 Google Maps API 時，可以在 URL 中使用 libraries 參數加入一些額外的功能，其使用方式可以參考 Libraries。

非同步載入（Asynchronously Loading）API

如果想要使用非同步載入的方式，讓 Google 地圖的 API 延後載入，不要讓 API 拖慢整體網頁的速度，可以使用下面這樣的方式：

function initialize() {
  var mapOptions = {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644)
  };

  var map = new google.maps.Map(document.getElementById('map-canvas'),
      mapOptions);
}

function loadScript() {
  var script = document.createElement('script');
  script.type = 'text/javascript';
  script.src = 'https://maps.googleapis.com/maps/api/js?v=3.exp' +
      '&signed_in=true&callback=initialize';
  document.body.appendChild(script);
}

window.onload = loadScript;

這裡在載入 API 的 JavaScript 時，加入一個 callback 參數，指定在 API 完全載入後的回呼函數，透過這樣的方式確保 initialize() 會在 API 載入完成後執行。

放置地圖的 DOM 元素

在使用 Google 地圖 API 時，我們需要保留一個顯示地圖用的地方，通常最常見的方式就是新增一個 <div> 元素，並且為的個元素命名，然後從 DOM 取得這個元素傳給 API：

<div id="map-canvas" style="width: 100%; height: 100%"></div>

這裡我們可以自行利用 CSS 調整它的大小，Google 地圖會自動依據包含地圖的元素大小來繪製地圖。

地圖選項

建立地圖時，都會需要至指定地圖中心（center）與縮放層級（zoom）這兩個參數。

var mapOptions = {
  center: new google.maps.LatLng(-34.397, 150.644),
  zoom: 8
};

地圖中心的經緯度可以使用下面三種方式來指定：

center: new google.maps.LatLng(-34.397, 150.644)
center: {lat: -34.397, lng: 150.644}
center: {lng: 150.644, lat: -34.397}

縮放層級的數值越小，顯示的範圍越大，當設為 0 時，則會顯示最大的範圍（世界地圖）。

地圖物件

Google 的地圖是以 Map 這個類別來代表的，一個 Map 物件代表一個地圖。

var map = new google.maps.Map(
    document.getElementById("map-canvas"),
    mapOptions);

您可以在一個網頁中同時產生多的 Map 物件，建立多個地圖。

在建立 Map 物件時，要連同 container 一起指定，這裡我們是使用 document.getElementById() 來取得作為 container 的 <div> 元素。

載入地圖

為了確保地圖會在網頁載入之後才進行繪製，避免一些不可預期的問題，我們在 onload 事件發生之後才執行繪製地圖的 JavaScript 程式：

google.maps.event.addDomListener(window, 'load', initialize);

您也可以直接寫在 <body> 標籤的 onload 屬性中：

<body onload="initialize()">

參考資料：Google Developers

3 留言

Leo

你好小弟我最近在利用google所提供的api做有關geolocation應用，我打算首先先讓範例程式run起來（https://developers.google.com/maps/documentation/javascript/examples/map-geolocation?hl=zh-tw）
但我按照範例在sublime上實作，連上線後發現出現的是
http://imgur.com/71UqO1F
無法抓到坐標
我以為是google api key的問題
我也回去看是啟動的
在網站上面的範例在google的網站是可以運作的
可是為什麼到了自己的空間卻不行呢？
想請教一下

2016/11/01
- jason
  
  我也遇到相同情況，也想知道問題點
  
  2017/11/23
- kai
  
  要開 server 才能看到
  在你的命令提示字元下 python -m SimpleHTTPServer (沒有python要裝或是找其他方式開 server)
  再來就去他給你的網址+port就可以看到了
  
  2018/10/22