嵌入地圖

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

建立 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 地圖模式在艾菲爾鐵塔顯示地圖標記：

您可以使用下列參數：

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

view模式

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

您可以使用下列參數：

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

directions模式

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

您可以使用下列參數：

參數	類型	說明	接受的值
origin	必要	定義顯示路線的起點。	網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。在轉義空格時，Maps Embed API 支援 + 和 %20。例如將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或將 Plus Code「849VCWC8+R9」轉換為 849VCWC8%2BR9。
destination	必要	定義路線的終點。	網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。逸出聊天室時，Maps Embed API 支援 + 和 %20。例如，將「City Hall, New York, 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	選用	根據地緣政治敏感度，定義適當的邊界和標籤。	接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 兩位字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。

streetview模式

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

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

請參閱下列 streetview 模式全景：

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

• 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	選用	根據地緣政治敏感度，定義適當的邊界和標籤。	接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 兩位字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。

search模式

Search 模式會顯示搜尋結果，搜尋可見地圖區域。建議您定義搜尋位置，方法是將地點加入搜尋字詞 (record+stores+in+Seattle)，或是加入 center 和 zoom 參數來限制搜尋範圍。

您可以使用下列參數：

參數	類型	說明	接受的值
q	必要	定義搜尋字詞。	可能包含地理區域限制，例如 in+Seattle 或 near+98033。
center	選用	定義地圖檢視的中心。	接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom	選用	設定地圖的初始縮放等級。	值的範圍從 0 (全世界) 到 21 (個別建築物)。上限可能因所選位置的可用地圖資料而異。
maptype	選用	定義要載入的地圖圖塊類型。	roadmap (預設) 或 satellite
language	選用	定義 UI 元素和地圖圖塊上標籤顯示的語言。根據預設，訪客會看到以自己語言顯示的地圖。這個參數僅適用於某些國家/地區圖塊；如果圖塊集不支援要求的特定語言，則會使用該圖塊集的預設語言。
region	選用	根據地緣政治敏感度，定義適當的邊界和標籤。	接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 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，因為無論在室內還是室外都不明。