嵌入地圖

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

建立 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 必要 用於定義地圖標記位置。 網址逸出的地點名稱、地址、加號代碼或地點 ID。 逸出空間時，Maps Embed API 支援 + 和 %20。例如，將「臺北市市政廳」轉換成「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 模式來顯示 Oslow 與 Telemark、挪威、距離和行駛時間之間的路徑，避免避開收費路段及高速公路。

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

您可以使用下列參數：

參數 類型 說明 接受的值
origin 必要 定義起點以顯示起點。 網址逸出的地點名稱、地址、加號、緯度/經度座標或地點 ID。逸出空間時，Maps Embed API 支援 + 和 %20。例如，將「臺北市市政廳」轉換成「City+Hall,New+York,NY」，或是用「849VCWC8+R9」加大代碼轉換為 849VCWC8%2BR9。
destination 必要 定義路線的終點。 網址逸出的地點名稱、地址、加號、緯度/經度座標或地點 ID。逸出空間時，Maps Embed API 支援 + 和 %20。例如，將「臺北市市政廳」轉換成「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 能讓您將街景服務圖像的全景區域顯示為互動式全景。您也可以使用使用者提供的 Photopheres 和街景服務特殊集錦。

每個街景服務全景都可讓您透過單一位置提供完整的 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 只會限制在戶外搜尋搜尋結果。室內集合不含搜尋結果。請注意，室外全景可能不適用於特定位置。另請注意，搜尋只會傳回能判斷室內或室外的全景。舉例來說，但由於 PhotoSpheres 屬於室內或室外環境，因此未傳回。