嵌入地圖

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

建立 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。

選擇地圖模式

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

• place：在特定地點或地址 (例如地標、商家、地理特徵或城鎮) 顯示地圖圖釘。
• view：傳回沒有標記或路線的地圖。
• directions：顯示地圖上兩個或多個指定點之間的路徑，以及距離和行程時間。
• streetview：顯示指定地點的互動式全景檢視畫面。
• search：顯示可見地圖區域的搜尋結果。

place模式

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

您可以使用下列參數：

參數	類型	說明	接受的值
q	必要	定義地圖標記位置。	經過網址逸出的地點名稱、地址、加號代碼或地點 ID。 逸出空格時，Maps Embed API 支援 + 和 %20。舉例來說，將「City Hall, New York, 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 參數，顯示地圖的衛星檢視畫面：

您可以使用下列參數：

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

directions模式

以下範例使用 directions 模式顯示挪威奧斯陸和泰勒馬克之間的路線、距離和行車時間，並避開收費路段和高速公路。

您可以使用下列參數：

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

streetview模式

透過 Maps Embed API，您可以在涵蓋範圍內指定位置，以互動式全景顯示街景服務圖像。此外，你也可以查看使用者提供的 360 度全景相片和街景服務特別收藏。

每個街景服務全景都提供單一位置的 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	選用	根據地緣政治敏感度，定義要顯示的適當邊界和標籤。	接受區碼，指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記，對應至熟悉的 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	選用	根據地緣政治敏感度，定義要顯示的適當邊界和標籤。	接受區碼，指定為雙字元 (非數字) 萬國碼 (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 會將搜尋範圍限制在室外集錦。搜尋結果不會顯示室內收藏內容。請注意，室外全景可能不適用於特定位置。另請注意，搜尋只會傳回可判斷是否為室內或室外的全景。舉例來說，系統不會傳回全景相片，因為無法判斷全景相片是在室內還是室外拍攝。