嵌入地圖

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

建立 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 標頭，因此 可能正常運作。

您可以配合網站的結構和設計調整 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, New York, NY」到 City+Hall,New+York,NY，或 Plus Codes「849VCWC8+R9」到 849VCWC8%2BR9。
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值；例如： 37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (每棟建築物)。上限可能會因地圖資料而異 可在所選位置使用
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和顯示 標籤上。根據預設，訪客可以自行建立地圖 語言。這個參數僅適用於部分國家/地區圖塊；如果 方塊集不支援您要求的特定語言，那麼 該方塊集的預設語言。
region 選用 定義要顯示的適當邊界和標籤 (依據： 對地緣政治敏感度的影響 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值請參閱 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 選用 定義要顯示的適當邊界和標籤 (依據： 對地緣政治敏感度的影響 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值請參閱 Google 地圖平台 支援區域的涵蓋範圍詳細資料。

directions模式

以下範例使用 directions 模式顯示 Oslow 之間的路徑 和交通時間，以及避開收費路段和高速公路的交通時間。

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, New York, NY」到 City+Hall,New+York,NY，或 Plus Codes「849VCWC8+R9」到 849VCWC8%2BR9。
destination 必要 定義路線的終點。 網址逸出的地點名稱、地址、plus code、經緯度 座標或地點 ID。 Maps Embed API 同時支援 + 和 %20 擷取空格。例如，將「City Hall, New York, NY」到 City+Hall,New+York,NY，或 Plus Codes「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 選用 定義要顯示的適當邊界和標籤 (依據： 對地緣政治敏感度的影響 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值請參閱 Google 地圖平台 支援區域的涵蓋範圍詳細資料。

streetview模式

Maps Embed API 可顯示街景服務圖片； 即可從指定地點拍攝的互動式全景相片 使用者 貢獻的全景相片，以及 街景服務集錦 您也可以使用

每個街景服務全景都提供單一的 360 度環景 或 HTTP/HTTPS 位置圖片包含 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 找不到全景時，才會使用 location 編號。

以下為選用網址參數：

參數 類型 說明 接受的值
heading 選用 指出相機的指南針方向 (以度為單位) 從北美開始 介於 -180° 到 360° 之間的值
pitch 選用 會指定相機的角度、向上或向下。正值會有角度 相機朝上，而負值會將相機向下角。 系統會依據相機位置， 已擷取圖片。因此通常音高為 0° 不一定每次都是橫向舉例來說，從山丘上拍攝的圖片 會顯示非水平的預設傾斜角度。 介於 -90° 到 90° 之間的值
fov 選用 會決定圖片的水平視野。這項服務 預設為 90°。處理固定大小的可視區域時 系統會將視圖視為縮放等級，較小的數字表示 以度為單位的數值，範圍介於 10° - 100°
center 選用 定義地圖檢視的中心。 接受以半形逗號分隔的經緯度值；例如： 37.4218,-122.0840。
zoom 選用 設定地圖的初始縮放等級。 範圍從 0 (全世界) 到 21 (每棟建築物)。上限可能會因地圖資料而異 可在所選位置使用
maptype 選用 定義要載入的地圖圖塊類型。 roadmap (預設) 或 satellite
language 選用 定義 UI 元素和顯示 標籤上。根據預設，訪客可以自行建立地圖 語言。這個參數僅適用於部分國家/地區圖塊；如果 方塊集不支援您要求的特定語言，那麼 該方塊集的預設語言。
region 選用 定義要顯示的適當邊界和標籤 (依據： 對地緣政治敏感度的影響 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值請參閱 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 選用 定義要顯示的適當邊界和標籤 (依據： 對地緣政治敏感度的影響 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值請參閱 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 會將搜尋範圍限制在室外集錦。室內 集合不會包含在搜尋結果中。請注意，室外全景 指定的地區沒有存在。另請注意，只有搜尋項目 會傳回全景，以判斷其是否位於室內 或是室外環境舉例來說，由於系統不明，因此不會傳回 PhotoSpheres 無論在室內還是室外都沒問題