嵌入地圖

本指南說明如何在您的網頁中嵌入互動式地圖。

建立 Maps Embed API 網址

以下是載入 Maps Embed API 的範例網址：

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

取代下列項目：

  • 用地圖模式為 MAP_MODE。
  • 將 YOUR_API_KEY 替換為您的 API 金鑰。詳情請參閱「取得 API 金鑰」。
  • PARAMETERS 包含地圖模式的必要和選用參數。

在 iframe 中加入網址

如要在網頁上使用 Maps Embed API，請將您建立的網址設為 iframe 的 src 屬性值。使用 iframe 的 height 和 width 屬性控制地圖大小，例如：

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

上述 iframe 範例使用其他屬性：

  • allowfullscreen 屬性可讓特定地圖部分進入全螢幕模式。
  • frameborder="0" 和 style="border:0" 屬性可移除地圖周圍的標準 iframe 邊框。
  • referrerpolicy="no-referrer-when-downgrade" 屬性可讓瀏覽器隨要求以 Referer 標頭傳送完整網址，以便 API 金鑰限制正常運作。

您可以配合自家網站的結構與設計調整 iframe 的大小，但我們發現，訪客通常比較容易與大型地圖互動。請注意，內嵌地圖並不支援小於 200 像素的任一維度。

API 金鑰限制

如果代管網站的 referrer 中繼標記設為 no-referrer 或 same-origin，瀏覽器就不會傳送 Referer 標頭給 Google。這可能會導致您的 API 金鑰限制拒絕要求。為了讓這項限制正常運作，請在 iframe 中新增 referrerpolicy 屬性 (如上例所示)，明確允許將 Referer 標頭傳送至 Google。

地圖上的廣告

Maps Embed API 可能包含地圖上的廣告。任何特定地圖中顯示的廣告格式和廣告組合可能會變更，恕不另行通知。

選擇地圖模式

您可以在要求網址中指定下列其中一種地圖模式：

  • place：顯示特定地點或地址的地圖圖釘，例如地標、商家、地貌或鄉鎮。
  • view：傳回不含標記或路線的地圖。
  • directions：顯示地圖上兩個以上指定點之間的路徑，以及距離和行程時間。
  • streetview：顯示指定位置的互動式全景。
  • search：顯示搜尋結果，範圍涵蓋可見地圖區域。

place模式

下列網址使用 place 地圖模式在艾菲爾鐵塔顯示地圖標記：

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

您可以使用下列參數：

參數 類型 說明 接受的值
q 必要 定義地圖標記位置。 網址逸出的地點名稱、地址、Plus Code 或地點 ID。 逸出聊天室時，Maps Embed API 支援 + 和 %20。例如，將「City Hall, NY, NY」轉換為 City+Hall,New+York,NY，或將代碼「849VCWC8+R9」轉換為 849VCWC8%2BR9。
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置提供的地圖資料而異。
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會使用慣用語言建立地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
region 選用 根據地緣政治敏感度，定義適當的邊界和標籤。 接受以雙字元 (非數字) 萬國碼 (Unicode) 區域子標記對應的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如要瞭解支援區域，請參閱 Google 地圖平台涵蓋範圍詳細資料。

view模式

以下範例使用 view 模式和選用的 maptype 參數來顯示地圖的衛星檢視：

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

您可以使用下列參數：

參數 類型 說明 接受的值
center 必要 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置提供的地圖資料而異。
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會使用慣用語言建立地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
region 選用 根據地緣政治敏感度，定義適當的邊界和標籤。 接受以雙字元 (非數字) 萬國碼 (Unicode) 區域子標記對應的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如要瞭解支援區域，請參閱 Google 地圖平台涵蓋範圍詳細資料。

directions模式

以下範例使用 directions 模式顯示奧斯洛和電信、挪威、距離，以及避開收費路段和高速公路的所需時間。

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

您可以使用下列參數：

參數 類型 說明 接受的值
origin 必要 定義顯示路線的起點。 網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。逸出聊天室時，Maps Embed API 支援 + 和 %20。例如，將「City Hall, NY, NY」轉換為 City+Hall,New+York,NY，或將代碼「849VCWC8+R9」轉換為 849VCWC8%2BR9。
destination 必要 定義路線的終點。 網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。逸出聊天室時，Maps Embed API 支援 + 和 %20。例如，將「City Hall, NY, NY」轉換為 City+Hall,New+York,NY，或將代碼「849VCWC8+R9」轉換為 849VCWC8%2BR9。
waypoints 選用 指定一或多個中介地點，以在起點和目的地之間規劃路線。 地點名稱、地址或地點 ID。 您可以使用直立線字元 (|) 來指定多個路線控點，例如 Berlin,Germany|Paris,France。您最多可以指定 20 個路線控點。
mode 選用 定義交通方式。如未指定模式，Maps Embed API 會顯示指定路線中一或多個最相關的模式。 driving、walking (偏好人行道和人行道，如有)、bicycling (如適用，可行駛單車道與專用街道)、transit 或 flying。
avoid 選用 指定方向要避免的功能。請注意，這不代表系統會排除含有受限地圖項目的路線，而是會將結果調整成您較偏好的路線。 tolls、ferries 和/或 highways。 請以直立線字元分隔多個值 (例如 avoid=tolls|highways)。
units 選用 在結果中顯示距離時，指定測量方法 (公制) 或英制。在未指定 units 的情況下，系統會根據查詢的 origin 國家/地區來決定要使用的單位。 metric 或 imperial
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置提供的地圖資料而異。
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會使用慣用語言建立地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
region 選用 根據地緣政治敏感度，定義適當的邊界和標籤。 接受以雙字元 (非數字) 萬國碼 (Unicode) 區域子標記對應的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如要瞭解支援區域，請參閱 Google 地圖平台涵蓋範圍詳細資料。

streetview模式

Maps Embed API 可讓您在指定地點的涵蓋範圍內，以互動式全景顯示街景服務圖片。此外，我們也提供使用者提供的全景相片和街景服務集錦。

每個街景服務全景都提供單一位置的 360 度完整檢視畫面。圖片包含 360 度的水平視圖 (全環景) 與 180 度的垂直視圖 (由正上方到正下方)。streetview 模式提供的檢視器會將產生的全景算繪為球體，攝影機則位於其中央。您可以藉由操控攝影機，控制攝影機的縮放和方向。

請參閱下列 streetview 模式全景：

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

你必須提供以下其中一個網址參數：

  • location 接受經緯度以逗號分隔的值 (46.414382,10.013988)。API 會顯示最靠近這個位置的全景。由於街景服務圖像會定期更新，而且每次拍攝的位置可能稍有不同，因此圖像更新後，地點可能會對齊其他全景。

  • pano 是特定的全景 ID。如果您指定 pano，也可以指定 location。只有在 API 找不到全景 ID 時，系統才會使用 location。

以下為選用網址參數：

參數 類型 說明 接受的值
heading 選用 指出相機的指南針方向 (以度為單位，從北順時針角度)。 介於 -180° 到 360° 之間的值
pitch 選用 會指定相機的角度、向上或向下。正值會將攝影機向上傾斜，負值則會將相機角度向下。預設的傾斜角度為 0°，根據拍照時相機的位置而定。因此，通常音高為 0°，但有時並非水平。舉例來說，在山上拍攝的圖片中，預設傾斜角度可能就不是水平。 介於 -90° 到 90° 之間的值
fov 選用 會決定圖片的水平視野。預設值為 90°。處理固定大小的可視區域時，可將視野視為縮放等級，數字越小表示縮放等級越高。 以度為單位的數值，範圍介於 10° - 100°
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置提供的地圖資料而異。
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會使用慣用語言建立地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
region 選用 根據地緣政治敏感度，定義適當的邊界和標籤。 接受以雙字元 (非數字) 萬國碼 (Unicode) 區域子標記對應的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如要瞭解支援區域，請參閱 Google 地圖平台涵蓋範圍詳細資料。

search模式

Search 模式會顯示搜尋結果，搜尋可見地圖區域。建議您在搜尋字詞中加入位置 (record+stores+in+Seattle) 或加入 center 和 zoom 參數來定義搜尋的位置。

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

您可以使用下列參數：

參數 類型 說明 接受的值
q 必要 定義搜尋字詞。 可能包含地理區域限制，例如 in+Seattle 或 near+98033。
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置提供的地圖資料而異。
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會使用慣用語言建立地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
region 選用 根據地緣政治敏感度，定義適當的邊界和標籤。 接受以雙字元 (非數字) 萬國碼 (Unicode) 區域子標記對應的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如要瞭解支援區域，請參閱 Google 地圖平台涵蓋範圍詳細資料。

地點 ID 參數

Maps Embed API 支援使用地點 ID，而非提供地點名稱或地址。地點 ID 是唯一識別地點的方式。詳情請參閱 Google Places API 說明文件。

Maps Embed API 接受下列網址參數的地點 ID：

  • q
  • origin
  • destination
  • waypoints

如要使用地點 ID，您必須先加入前置字串 place_id:。以下程式碼將紐約市大廳指定為路線要求的起點：origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8。

  • radius 會設定半徑 (以公尺為單位)，以指定經緯度為中心搜尋全景。有效值是非負整數。預設值為 50。

  • source 會將街景服務搜尋範圍限制在所選來源。以下為有效值：

    • default 會使用街景服務的預設來源。搜尋範圍不限於特定來源。
    • outdoor 會將搜尋範圍限制在室外集錦。搜尋結果不會包含室內集合。請注意，室外全景可能不適用於特定位置。此外請注意，搜尋作業只會在可能的情況下傳回全景，以判斷圖片為室內或室外。舉例來說，系統不會傳回 PhotoSphere，因為無論在室內還是室外都不明。